@vibesdotdev/auth 0.0.0-stage → 1.0.0-rc.3

package/dist/docs/flows.docs.descriptor.js

@@ -0,0 +1,192 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'auth.flows',
+    title: 'Authentication Flows',
+    summary: 'Authentication flows including sign-in, sign-up, sign-out, OAuth redirects, and CLI device login',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Authentication Flows
+summary: Authentication flows including sign-in, sign-up, sign-out, OAuth redirects, and CLI device login
+tags: [auth, flows, sign-in, sign-up, sign-out, oauth, cli]
+parent: auth
+order: 1
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+id: auth.flows
+---
+
+# Authentication Flows
+
+The auth runtime is owned solely by \`apps/auth-web\` (auth.vibes.dev). Every surface — Svelte components, CLI commands, browser stores — drives the same flows through the canonical \`AuthApiClient\`, resolved at runtime via \`getVibesClient<AuthApiClient>('auth', runtime)\`. The client speaks to better-auth over HTTP and forwards \`credentials: 'include'\` on every request, so sessions are carried by cookies (there is no bearer-token surface and no client-side token storage).
+
+Native desktop sign-in is the deliberate exception to browser cookie custody:
+\`auth/device-session#auth.device-session\` runs RFC 8628 inside the trusted
+consumer worker, stores durable credentials only through
+\`secrets/store#encrypted-local\`, and remotely exposes a strict safe snapshot.
+The browser may receive a user code, verification URL, expiry, state, and user
+identity; it never receives the RFC device code or any durable credential.
+Callers may select an environment id, and both the canonical \`apps.auth\`
+origin and credential partition resolve from that same descriptor.
+
+## Resolving the client
+
+\`AuthApiClient\` is **not** a top-level export — there is no \`authClient\` singleton to import. Resolve an instance through the runtime client and call \`ensureLoaded()\` once before use:
+
+\`\`\`ts
+import { getVibesClient } from '@vibesdotdev/kernel/client';
+import type { AuthApiClient } from '@vibesdotdev/auth/api';
+
+const client = await getVibesClient<AuthApiClient>('auth', runtime);
+await client.ensureLoaded();
+\`\`\`
+
+The full contract (see \`@vibesdotdev/auth/api\`):
+
+\`\`\`ts
+interface AuthApiClient {
+  ensureLoaded(): Promise<void>;
+  readonly authOrigin: string;
+  signInEmail(input: EmailPasswordCredentials): Promise<AuthSession>;
+  signUpEmail(input: AuthSignUpCredentials): Promise<AuthSession>;
+  signOut(): Promise<void>;
+  getSession(): Promise<AuthSession>;
+  providerSignInUrl(providerId: AuthProviderId, opts?): string;
+  providerSignUpUrl(providerId: AuthProviderId, opts?): string;
+}
+\`\`\`
+
+## Sign-in flow
+
+### Email / password
+
+\`signInEmail\` POSTs to \`/api/auth/sign-in/email\` and resolves with the established session.
+
+\`\`\`ts
+const session = await client.signInEmail({
+  email: 'user@example.com',
+  password: 'secure-password',
+  rememberMe: true,        // optional; persists beyond the browser session
+  callbackURL: '/dashboard' // optional; passed through to better-auth
+});
+
+console.log(session.user);    // AuthSessionUser | null
+console.log(session.session); // { id, userId, expiresAt } | null
+\`\`\`
+
+A successful response sets the session cookie. \`session.user\` is \`null\` when no session is established.
+
+### OAuth provider redirects
+
+The client does **not** fetch for OAuth — \`providerSignInUrl\` / \`providerSignUpUrl\` build the redirect URL (default path \`/api/auth/sign-in/{providerId}\`), and the surface navigates the browser there:
+
+\`\`\`ts
+const url = client.providerSignInUrl('github', { redirectTo: '/dashboard' });
+window.location.assign(url);
+\`\`\`
+
+Supported provider ids include \`github\`, \`google\`, \`discord\`, \`apple\`, \`microsoft\`, and \`email\`. See [\`auth.oauth\`](auth.oauth) for provider configuration.
+
+## Sign-up flow
+
+\`signUpEmail\` POSTs to \`/api/auth/sign-up/email\` with an optional display name:
+
+\`\`\`ts
+const session = await client.signUpEmail({
+  email: 'newuser@example.com',
+  password: 'secure-password',
+  name: 'New User'
+});
+\`\`\`
+
+## Sign-out flow
+
+\`signOut\` POSTs to \`/api/auth/sign-out\`, clearing the active session cookie:
+
+\`\`\`ts
+await client.signOut();
+\`\`\`
+
+## Reading the current session
+
+\`getSession\` GETs \`/api/auth/session\`. It always resolves (it does not throw when signed out); \`user\` is \`null\` when unauthenticated:
+
+\`\`\`ts
+const session = await client.getSession();
+if (session.user) {
+  // signed in
+}
+\`\`\`
+
+## CLI flows
+
+The CLI resolves the same auth runtime under the hood. The user-facing commands are:
+
+\`\`\`shell
+vibes auth login          # interactive sign-in (email/password)
+vibes auth login --token <api-key>   # validate + persist an API key
+vibes auth logout         # clear the stored session credential
+vibes auth logout --all   # also revoke server-side sessions
+vibes auth status         # show the current auth status
+vibes auth token          # show / refresh / validate the active token
+\`\`\`
+
+### Device-code login (RFC 8628)
+
+\`vibes auth login\` can authenticate without a password by running the OAuth 2.0 device-authorization flow:
+
+1. The CLI requests a device code from \`POST /api/auth/device/code\`.
+2. It prints the \`user_code\` and opens the \`verification_uri\` returned by the server.
+3. The user approves in the browser.
+4. The CLI polls the token endpoint (\`grant_type: urn:ietf:params:oauth:grant-type:device_code\`) until approval, denial, or expiry.
+5. The resulting \`access_token\` is stored as a session credential via the unified credential store.
+
+CLI sessions request a scoped set of capabilities (e.g. \`profile:read\`, \`agents:read\`, \`agents:run\`, \`knowledge:read\`).
+
+## Error handling
+
+Client methods reject with typed errors from \`@vibesdotdev/auth/api\`:
+
+\`\`\`ts
+import { AuthClientError, AuthNotSignedInError } from '@vibesdotdev/auth/api';
+
+try {
+  await client.signInEmail({ email, password });
+} catch (error) {
+  if (error instanceof AuthClientError) {
+    console.error(error.status, error.message); // HTTP status + message
+  } else if (error instanceof AuthNotSignedInError) {
+    // no active session for an operation that required one
+  }
+}
+\`\`\`
+
+For user-facing copy, map raw errors to friendly strings with \`getAuthErrorMessage\`:
+
+\`\`\`ts
+import { getAuthErrorMessage } from '@vibesdotdev/auth/features/core/shared/auth-errors';
+
+const message = getAuthErrorMessage(error);
+\`\`\`
+
+## Session management
+
+See [\`auth.sessions\`](auth.sessions) for session lifecycle, validation, and JWT handle details.
+
+:::card{title="See also"}
+- [\`auth.sessions\`](auth.sessions) — Session lifecycle and validation
+- [\`auth.oauth\`](auth.oauth) — OAuth provider configuration
+- [\`auth.providers\`](auth.providers) — Auth provider runtime kind
+:::
+`
+    },
+    parent: 'auth',
+    order: 1,
+    tags: ['auth', 'flows', 'sign-in', 'sign-up', 'sign-out', 'oauth', 'cli'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=flows.docs.descriptor.js.map

package/dist/docs/flows.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/flows.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,YAAY;IAChB,KAAK,EAAE,sBAAsB;IAC7B,OAAO,EAAE,kGAAkG;IAC3G,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6KT;KACC;IACD,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC;IACzE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/keys.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=keys.docs.descriptor.d.ts.map

package/dist/docs/keys.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/keys.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBAoPjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/keys.docs.descriptor.js

@@ -0,0 +1,247 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'auth.keys',
+    title: 'Key Envelopes',
+    summary: 'Ed25519 did:key identities, recipient key bundles, and sign-then-encrypt envelopes',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Key Envelopes
+summary: Ed25519 did:key identities, recipient key bundles, and sign-then-encrypt envelopes
+tags: [auth, keys, did, envelope, encryption, signature, replay]
+id: auth.keys
+parent: auth
+order: 5
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Key Envelopes
+
+\`@vibesdotdev/auth/keys\` is the versioned wire contract for device-to-device
+messages: a device identity is an Ed25519 **did:key**, a device publishes a
+self-signed **recipient key bundle** naming its X25519 agreement key, and a
+sender seals a **sign-then-encrypt envelope** to that bundle. Only the
+recipient device can open it, and it learns who sent it only after
+decrypting.
+
+The export is universal. Its closure is jose's WebCrypto build, \`zod/v4\`, the
+\`@vibesdotdev/runtime\` root (for \`CapabilityError\`) and sibling files; it never
+imports \`node:crypto\` or a Bun API.
+
+## Custody and the replay guard
+
+Features do not hold device keys or build replay guards. They resolve the
+\`auth/key\` kind, which keeps keys in custody and supplies a storage-backed
+guard. This export is the primitive layer that kind wraps. Device key
+generation and every guard implementation are deliberately not exported: a
+process-local seen-set is fake replay protection across isolates.
+
+## did:key codec
+
+- \`ed25519DidKeySchema\`: an Ed25519 did:key string. A regex prefilter
+  (\`did:key:z6Mk\` plus 44 base58btc characters) and then the full codec,
+  because a regex-only match can decode to another multicodec. The prefilter
+  aborts, so the codec never runs on a string it refused.
+- \`ed25519PublicKeyFromDidKey(did)\`: the raw 32-byte key. Decode order:
+  the \`did:key:\` prefix, the \`z\` multibase prefix, a multibase of at most
+  1024 characters, the base58btc alphabet (all \`malformed_did\`), then the
+  multicodec. Any codec other than Ed25519 (0xed), for example X25519 or
+  P-256, is \`unsupported_key_type\`; an Ed25519 payload that is not 32 bytes
+  is \`malformed_did\`. The length bound runs before decoding because base58
+  decoding is quadratic and a kid, iss or aud reaches it before any signature
+  is checked. It admits every key type the did:key method registers (RSA-4096,
+  the largest, is 722 characters).
+- \`didKeyFromEd25519PublicKey(bytes)\`: the inverse. It refuses any key the
+  decoder would refuse.
+- \`didKeyVerificationMethodId(did)\`: \`did + '#' + multibase\`, the \`kid\`
+  every signed token carries.
+- \`importDidKeyVerificationKey(did)\`: a verify-only WebCrypto Ed25519 key.
+
+### Strict Ed25519 acceptance
+
+WebCrypto Ed25519 verify does not reject small-order points: Bun 1.4.0 and
+Chromium 151 both verify the universal forgery (public key = identity point,
+R = identity, S = 0) as true for every message. So nothing reaches
+\`crypto.subtle.verify\` unless:
+
+- the public key is a canonical encoding of a point on the curve in the
+  prime-order subgroup (not small-order, not mixed-order). A did:key naming
+  any other key is \`malformed_did\`, and \`ed25519DidKeySchema\` rejects it;
+- the signature is 64 bytes, its R passes the same point rules, and S < L.
+  Anything else is \`bad_signature\`.
+
+For such inputs cofactored and cofactorless verification agree, so the verdict
+does not depend on the engine. This is the rule Hyperspace adopts as SIG2.
+
+## Recipient key bundle (v1)
+
+A compact JWS with protected header exactly \`{ alg: 'EdDSA', typ, kid }\`,
+where typ is \`RECIPIENT_KEY_BUNDLE_TYP\` (\`vibes-agreement-key+jwt\`) and kid is
+the device's verification method. Claims (strict, \`recipientKeyBundleClaimsV1Schema\`):
+
+\`\`\`ts
+{ v: 1, iss: did, kid: thumbprint(cnf.jwk), cnf: { jwk: X25519 public JWK },
+  envelopeVersions: [1], iat, exp }
+\`\`\`
+
+\`RECIPIENT_KEY_BUNDLE_VERSION\` is 1. \`x25519PublicJwkSchema\` is exactly
+\`{ kty: 'OKP', crv: 'X25519', x }\`. \`createRecipientKeyBundle(device, { ttlSeconds })\`
+signs one. \`verifyRecipientKeyBundle(bundle)\` returns frozen plain data
+(\`VerifiedRecipient\`: did, kid, publicJwk, envelopeVersions, issuedAt,
+expiresAt) with no CryptoKey, so it can cross runtime remote exposures. Check
+order: length over 4096 characters (\`too_large\`; a v1 bundle is 669), shape
+and header (\`malformed\`), typ (\`wrong_type\`), alg
+(\`unsupported_algorithm\`, before any key import), kid (\`malformed_did\` /
+\`unsupported_key_type\` / \`malformed\`), strict signature bytes and verify with
+the key named by kid (\`bad_signature\`), payload JSON (\`malformed\`), v
+(\`unsupported_version\`), cnf.jwk kty/crv (\`unsupported_key_type\`), strict
+claims (\`malformed\`), iss equals kid's did (\`sender_mismatch\`), kid equals the
+thumbprint (\`malformed\`), iat (\`not_yet_valid\`), exp (\`expired\`). The
+default clock tolerance is 30 seconds.
+
+## Envelope (v1)
+
+A compact JWE whose protected header is exactly
+\`{ alg: 'ECDH-ES', enc: 'A256GCM', cty: 'JWT', kid: <recipient agreement kid>, epk }\`.
+It wraps a compact JWS with header \`{ alg: 'EdDSA', typ: KEY_ENVELOPE_TYP, kid }\`
+(\`KEY_ENVELOPE_TYP\` is \`vibes-envelope+jwt\`) and strict claims
+(\`keyEnvelopeClaimsV1Schema\`):
+
+\`\`\`ts
+{ v: 1, iss: sender did, aud: recipient did, jti: 16 random bytes (base64url),
+  iat, exp, pld: payload }
+\`\`\`
+
+The sender's identity appears only inside the ciphertext. \`aud\` is
+mandatory, so an envelope re-encrypted to someone else is \`wrong_audience\`.
+
+\`\`\`ts
+import { openKeyEnvelope, sealKeyEnvelope } from '@vibesdotdev/auth/keys';
+
+const envelope = await sealKeyEnvelope({
+  sender,                    // KeyEnvelopeSender { did, signingKey }
+  recipientBundle,           // the recipient's bundle string
+  payloadSchema: messageSchema,
+  payload: { text: 'hi' },
+  ttlSeconds: 60
+});
+
+const opened = await openKeyEnvelope(envelope, {
+  recipient,                 // KeyEnvelopeRecipientKeys { did, agreement: { kid, privateKey } }
+  payloadSchema: messageSchema,
+  replayGuard,               // required, from the auth/key kind
+  acceptSender: (did) => trusted.has(did) // required
+});
+// OpenedKeyEnvelope: { sender, payload, jti, issuedAt, expiresAt, version }
+\`\`\`
+
+\`sealKeyEnvelope\` order: ttlSeconds must be a positive integer (\`malformed\`);
+it verifies the bundle string itself (the bundle's own codes); it negotiates
+the version (\`unsupported_version\`); it validates the payload
+(\`payload_invalid\`) and the sender did (\`malformed_did\`); then it signs and
+encrypts.
+
+\`openKeyEnvelope\` order, fail-closed:
+
+1. length over maxEnvelopeBytes (default 262144): \`too_large\`
+2. not five ASCII base64url segments, or a header that is not exactly the v1
+   JWE header: \`malformed\`
+3. header kid is not the recipient's agreement kid: \`wrong_recipient\`
+4. decryption (ECDH-ES and A256GCM only): \`decrypt_failed\`
+5. inner JWS shape: \`malformed\`; typ: \`wrong_type\`; alg: \`unsupported_algorithm\`;
+   kid: \`malformed_did\` / \`unsupported_key_type\` / \`malformed\`
+6. strict signature bytes, then verify with the key named by kid: \`bad_signature\`
+7. v: \`unsupported_version\`; strict v1 claims: \`malformed\`
+8. iss is not kid's did: \`sender_mismatch\`; aud is not the recipient: \`wrong_audience\`
+9. iat beyond now + tolerance: \`not_yet_valid\`; now beyond exp + tolerance:
+   \`expired\`; exp not after iat: \`malformed\`; lifetime over maxTtlSeconds
+   (default 300): \`ttl_exceeded\`
+10. acceptSender(iss) is not true: \`sender_not_accepted\`
+11. payloadSchema rejects pld: \`payload_invalid\`
+12. the replay claim: \`replayed\`
+
+Sender policy and payload validation run before the replay claim, so rejected
+envelopes and unaccepted senders consume no guard capacity. A
+NotSupportedError from WebCrypto at any step is \`unsupported_runtime\`.
+
+## Versioning
+
+A version's claims schema never changes; adding a claim means a new version.
+\`KEY_ENVELOPE_VERSIONS\` lists the versions this code reads and writes (today
+\`[1]\`). Bundles advertise \`envelopeVersions\`; a sender uses the highest
+version both sides support, or throws \`unsupported_version\` when there is
+none. A reader reads \`v\` from the verified payload before the strict parse,
+so an unknown version is \`unsupported_version\`, never \`malformed\`.
+
+## Replay guard contract
+
+\`KeyEnvelopeReplayGuard.claim({ sender, jti, retainUntil })\` records a claim
+(\`keyEnvelopeReplayClaimSchema\`). openKeyEnvelope passes
+\`retainUntil = exp + clockToleranceSeconds\`, the last second the envelope can
+still be accepted. An implementation must return \`'replayed'\` for any
+(sender, jti) claimed earlier whose retainUntil has not passed, must never
+forget an entry before retainUntil, and must throw \`replay_guard_full\` when it
+cannot record a claim instead of returning an unrecorded \`'fresh'\`. Only an
+explicit \`'fresh'\` opens an envelope. Time validity is rechecked before and
+after the asynchronous claim; slow policy, payload validation or storage cannot
+open an envelope after its replay-retention window.
+
+## Errors
+
+Every failure is a \`KeyEnvelopeError\`, a \`CapabilityError\` whose \`reason\` is
+one of these codes (\`keyEnvelopeErrorCodeSchema\`; also kept as \`legacyCode\`);
+no raw jose error or DOMException escapes, the failure that ended the step is
+its \`cause\`, and messages never carry key material, plaintext or payload values.
+
+| Reason | Meaning |
+| --- | --- |
+| \`malformed_did\` | not a did:key, a multibase over 1024 characters, not base58btc, wrong Ed25519 length, or a key the strict rule rejects |
+| \`unsupported_key_type\` | a non-Ed25519 did:key, a non-X25519 agreement key, or an unusable CryptoKey |
+| \`unsupported_runtime\` | WebCrypto in this runtime lacks Ed25519 or X25519 |
+| \`unsupported_algorithm\` | a JWS alg other than EdDSA |
+| \`unsupported_version\` | an unknown bundle or envelope version, or no mutual envelope version |
+| \`malformed\` | bad shape, header, claims, options, or thumbprint |
+| \`wrong_type\` | a token of the other typ (bundle vs envelope) |
+| \`too_large\` | the envelope exceeds maxEnvelopeBytes, or a bundle exceeds 4096 characters |
+| \`wrong_recipient\` | addressed to another agreement key |
+| \`decrypt_failed\` | the JWE does not decrypt |
+| \`bad_signature\` | the signature does not verify, or its bytes are not strict |
+| \`sender_mismatch\` | iss is not the did:key that signed |
+| \`wrong_audience\` | aud is not the opening device |
+| \`expired\` | past exp plus tolerance |
+| \`not_yet_valid\` | iat beyond now plus tolerance |
+| \`ttl_exceeded\` | lifetime above maxTtlSeconds |
+| \`sender_not_accepted\` | acceptSender refused the sender |
+| \`payload_invalid\` | the payload schema refused the payload |
+| \`replayed\` | the guard has seen this (sender, jti) |
+| \`replay_guard_full\` | the guard cannot record another claim |
+
+## Environments
+
+| Environment | Status |
+| --- | --- |
+| Bun 1.4.0 | proven (bun tests) |
+| Chromium 151 (Playwright headless) | proven (browser test) |
+| workerd, CEF, mobile webviews, Safari, Firefox | unproven |
+
+In an unproven environment that lacks Ed25519 or X25519, calls raise
+\`unsupported_runtime\` rather than claim support. The first consumer in each
+environment proves it.
+
+:::card{title="See also"}
+- [\`auth.sessions\`](auth.sessions) — Session Management
+- [\`auth.providers\`](auth.providers) — Auth provider interface
+:::
+`
+    },
+    parent: 'auth',
+    order: 5,
+    tags: ['auth', 'keys', 'did', 'envelope', 'encryption', 'signature', 'replay'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=keys.docs.descriptor.js.map

package/dist/docs/keys.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/keys.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,WAAW;IACf,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,oFAAoF;IAC7F,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoOT;KACC;IACD,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,CAAC;IAC9E,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/oauth.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=oauth.docs.descriptor.d.ts.map

package/dist/docs/oauth.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/oauth.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBA8KjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/oauth.docs.descriptor.js

@@ -0,0 +1,177 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'auth.oauth',
+    title: 'OAuth Authentication',
+    summary: 'OAuth providers, callbacks, and state management',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: OAuth Authentication
+summary: OAuth providers, callbacks, and state management
+tags: [auth, oauth, providers, callbacks, state]
+parent: auth
+order: 3
+id: auth.oauth
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# OAuth Authentication
+
+OAuth sign-in in vibes is driven by [Better Auth](auth.providers) running inside \`apps/auth-web\`. The auth runtime owns the full authorization-code exchange server-side; consumers never see a client secret, an authorization code, or a raw token. Instead, the canonical \`AuthApiClient\` builds the redirect URL for a provider and the browser navigates to it. The provider callback lands back on \`auth-web\`, which completes the exchange and sets a session cookie.
+
+Because of this, the \`@vibesdotdev/auth\` OAuth surface is intentionally small: a URL builder on the client plus Zod schemas for provider ids, callbacks, and state. There is no in-package OAuth plugin factory, no client-side code-exchange, and no account-linking API.
+
+## Supported Providers
+
+The \`oauthProviderSchema\` enum is the source of truth for which providers the OAuth feature schemas accept:
+
+| Provider | ID |
+|----------|----|
+| GitHub | \`github\` |
+| Google | \`google\` |
+| Discord | \`discord\` |
+
+The broader \`AuthProviderId\` type used by the client also accepts \`apple\`, \`microsoft\`, \`email\`, and any other string id configured on the Better Auth server. The set of providers actually offered to users is decided by \`auth-web\` configuration, not by this package.
+
+## Resolving the auth client
+
+Every consumer resolves the same canonical client through the runtime client registry. No surface package imports an implementation directly.
+
+\`\`\`ts
+import { getVibesClient } from '@vibesdotdev/kernel/client';
+import type { AuthApiClient } from '@vibesdotdev/auth/api';
+
+const client = await getVibesClient<AuthApiClient>('auth', runtime);
+await client.ensureLoaded(); // idempotent lazy-init
+\`\`\`
+
+## OAuth flow
+
+### Step 1: Build the provider redirect URL
+
+\`providerSignInUrl\` (and \`providerSignUpUrl\`) build a URL — they do not perform a fetch. Hand the result to the browser.
+
+\`\`\`ts
+const href = client.providerSignInUrl('github', {
+  // Where auth-web should send the user after a successful sign-in.
+  redirectTo: '/dashboard',
+  // Optional override; defaults to /api/auth/sign-in/{providerId}
+  signInPath: undefined
+});
+
+window.location.assign(href);
+\`\`\`
+
+For a sign-up entry point use the parallel builder:
+
+\`\`\`ts
+const href = client.providerSignUpUrl('google', { redirectTo: '/welcome' });
+window.location.assign(href);
+\`\`\`
+
+Both options bags are typed as a subset of \`AuthProviderUrlOptions\`:
+
+\`\`\`ts
+interface AuthProviderUrlOptions {
+  redirectTo?: string;
+  signInPath?: string;
+  signUpPath?: string;
+}
+\`\`\`
+
+### Step 2: Provider authorization + callback
+
+The browser is redirected to the provider, the user authorizes, and the provider redirects back to \`auth-web\` (the default path is \`/api/auth/sign-in/{providerId}\`). Better Auth performs the authorization-code exchange, applies CSRF/state validation, creates the user/session, and sets the session cookie. None of this runs in consumer code.
+
+### Step 3: Read the resulting session
+
+After the redirect resolves, read the session the same way as any other login:
+
+\`\`\`ts
+const session = await client.getSession();
+// { user: { id, email, name?, image? } | null, session?: {...} | null }
+
+if (session.user) {
+  // signed in
+}
+\`\`\`
+
+\`getSession()\` returns \`{ user: null, session: null }\` for an unauthenticated request rather than throwing.
+
+## OAuth schemas
+
+The package exports Zod schemas for validating OAuth-related payloads (callback params, state, provider settings). Import them from the package root.
+
+\`\`\`ts
+import {
+  oauthProviderSchema,
+  oauthCallbackSchema,
+  oauthStateSchema,
+  oauthProviderSettingsSchema
+} from '@vibesdotdev/auth';
+
+// Validate a callback query string on the server.
+const callback = oauthCallbackSchema.parse({
+  code: query.get('code'),
+  state: query.get('state') ?? undefined,
+  error: query.get('error') ?? undefined,
+  error_description: query.get('error_description') ?? undefined
+});
+\`\`\`
+
+\`oauthStateSchema\` describes the structured state Better Auth round-trips through the provider:
+
+\`\`\`ts
+interface OAuthState {
+  redirect?: string;
+  params?: Record<string, string>;
+  cliState?: string;     // set when the flow originated from the CLI
+  cliCallback?: string;
+}
+\`\`\`
+
+## Error handling
+
+The client throws typed errors. \`AuthClientError\` carries the HTTP \`status\`; \`AuthNotSignedInError\` is thrown when an authenticated call is made without a session.
+
+\`\`\`ts
+import { AuthClientError, AuthNotSignedInError } from '@vibesdotdev/auth/api';
+
+try {
+  const session = await client.getSession();
+  // ...
+} catch (err) {
+  if (err instanceof AuthNotSignedInError) {
+    window.location.assign(client.providerSignInUrl('github'));
+  } else if (err instanceof AuthClientError) {
+    console.error('auth request failed', err.status, err.message);
+  }
+}
+\`\`\`
+
+When a provider denies access it redirects back with \`error\` / \`error_description\` query params; validate them with \`oauthCallbackSchema\` and surface a friendly message rather than treating them as a thrown error.
+
+## Security notes
+
+- State and CSRF validation are handled by Better Auth on the server. Do not roll your own state token — the runtime does not expose a \`generateState\` helper.
+- The client never sees a client secret or authorization code; those live only in \`auth-web\` server config.
+- Sessions are cookie-based. Every client request sends \`credentials: 'include'\`; there is no bearer-token surface for OAuth.
+
+:::card{title="See also"}
+- [\`auth.flows\`](auth.flows) — Authentication flows
+- [\`auth.sessions\`](auth.sessions) — Session management
+- [\`auth.providers\`](auth.providers) — Authentication providers
+:::
+`
+    },
+    parent: 'auth',
+    order: 3,
+    tags: ['auth', 'oauth', 'providers', 'callbacks', 'state'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=oauth.docs.descriptor.js.map

package/dist/docs/oauth.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/oauth.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,YAAY;IAChB,KAAK,EAAE,sBAAsB;IAC7B,OAAO,EAAE,kDAAkD;IAC3D,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8JT;KACC;IACD,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC;IAC1D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/sessions.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=sessions.docs.descriptor.d.ts.map

package/dist/docs/sessions.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/sessions.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBAoSjB,CAAC;AAEF,eAAe,UAAU,CAAC"}