docs(auth): remove provider-specific terms from public spec - #812
docs(auth): remove provider-specific terms from public spec#812carsonp6 wants to merge 1 commit into
Conversation
Strip enclave/provider-specific vocabulary from the public Embedded
Wallet auth spec and Global Accounts docs, replacing it with generic,
accurate wording:
- "TEK" / "Target Encryption Key" -> "ephemeral P-256 keypair" /
"session signing key" / "the private key it generated", per context.
- Drop the gratuitous "enclave" framing in prose ("enclave key",
"signed enclave bundle", "the enclave expects") in favor of
"encryption target key" / "signed bundle" / "Grid expects".
- Regenerate the example OTP `payloadToSign` JWT so its header no
longer carries a provider name in `kid` (the token is illustrative
and opaque; the client stamps it byte-for-byte regardless).
Kept: HPKE (RFC 9180) where it is the load-bearing crypto standard the
client integration code genuinely uses (client-keys cipher-suite spec +
code samples) - it is a public IETF standard, not a provider identifier.
Wire-format examples that expose the real signed bytes
(`payloadToSign` activity JSON, `enclaveQuorumPublic` bundle envelopes)
are left untouched and flagged for a design call rather than falsified.
Bundle regenerated (`make build`); redocly + spectral lint clean
(0 errors); oasdiff reports no breaking changes.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs.
|
1 participant
Summary
Concern-separated cleanup pass: strip pre-existing enclave/provider-specific vocabulary from the public Embedded Wallet auth spec and Global Accounts docs, replacing it with generic, accurate wording. No behavior or schema changes — description/example text only.
Grid's public API surface should not tip readers off to the enclave provider or its proprietary internals. This removes that provider-specific vocabulary while keeping every doc accurate.
What was genericized (prose)
TEK/ "Target Encryption Key"kid":"turnkey"inside the example OTPpayloadToSignJWT header{"alg":"ES256"}header (token is illustrative/opaque; the client stamps it byte-for-byte either way)Files touched:
AuthMethodResponse,AuthSession,AuthSignedRequestChallenge,auth_credentials_{id}_verify,internal_accounts_{id}_export, and the Global Accounts snippets (authentication,client-keys,walkthrough,sandbox-global-account-magic). Bundle regenerated viamake build.What was KEPT (with reasoning) — please confirm
HPKE (RFC 9180). I deliberately kept
HPKE. It is a public IETF standard, not a provider identifier — many services use it, and it does not point at any particular enclave vendor. More importantly it is load-bearing: theclient-keysguide documents the exact cipher suite (DHKEM(P-256, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM) and the code samples import real HPKE libraries (@hpke/core, BouncyCastleHPKE, CryptoKitHPKE.Recipient). Genericizing it to "an encryption library" would make the integration guide non-functional and less accurate. Flagging per the "don't break accuracy" guidance — happy to strip it from narrative prose too if you'd rather, but it must stay in the cipher-suite spec + code.What was FLAGGED, not changed (needs a design call)
These expose the real signed wire format or the real returned envelope structure. Genericizing them would make the examples lie about the bytes the client signs/receives, so I left them as-is:
payloadToSignactivity-request JSON — the literal bytes the client stamps, containingACTIVITY_TYPE_*+"organizationId":"org_...":openapi/paths/auth/auth_credentials.yaml(UPDATE_USER_EMAIL / UPDATE_USER_PHONE_NUMBER / CREATE_OAUTH_PROVIDERS / CREATE_AUTHENTICATORS_V2)openapi/paths/customers/customers_{customerId}.yaml(UPDATE_USER_EMAIL / PHONE)openapi/paths/auth/auth_sessions_{id}_refresh.yaml(CREATE_READ_WRITE_SESSION_V2)openapi/paths/internal_accounts/internal_accounts_{id}.yaml(SIGN_RAW_PAYLOAD_V2)openapi/components/schemas/common/SignedRequestChallenge.yaml(ACTIVITY_TYPE_EXAMPLE)openapi/components/schemas/common/PaymentEmbeddedWalletInfo.yaml(SIGN_TRANSACTION_V2)authentication.mdx,exporting-wallet.mdx,walkthrough.mdx,managing-sessions.mdxenclaveQuorumPublicbundle envelope field — the real field name in the returned OTP-target / wallet-export bundles the client must parse (+ the export bundle's innerorganizationId). Renaming it would misrepresent the wire format. Appears inAuthMethodResponse,auth_credentials,auth_credentials_{id}_challenge,InternalAccountExportResponse, and the export/walkthrough snippets.Because the
payloadToSignvalue is the exact byte string the client signs, you cannot hide the activity-type/org-id format without either (a) lying about what's signed, or (b) changing howpayloadToSignis presented (e.g. an opaque base64 the client signs blindly). That is a product/design decision, not a docs edit — hence flagged rather than guessed.Validation
make build— bundle regenerated,openapi.yaml+mintlify/openapi.yamlin sync with sources.make lint(redocly + spectral) — 0 errors (remaining 147 warnings / 511 infos are pre-existing on unrelated schemas: BRL/CAD/COP/Stablecoin/etc.).oasdiff breakingvs base — no breaking changes (description/example text only).🤖 Generated with Claude Code