@ultimat3/auth 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# @ultimat3/auth 🔐
+
+**The output of authentication is an `Actor` from `@ultimat3/core`.** Nothing downstream
+authorizes on a session row, a user row or an api key — http, actions, jobs and MCP all read
+`ctx.actor` and hand it to `@ultimat3/policy`. One authz system, never two.
+
+```ts
+import { BuiltinAdapter, defineAuth, login } from '@ultimat3/auth';
+
+export const auth = defineAuth({
+  adapter: new BuiltinAdapter(),          // or MemoryAdapter, or your Better Auth binding
+  session: { absoluteTtlMs: 30 * 864e5, idleTtlMs: 7 * 864e5 },
+  password: { minLength: 12 },
+  mfa: { issuer: 'Acme' },
+  providers: ['github', 'google'],
+});
+
+const { actor, token, cookie } = await login(auth, { email, password, ip });
+```
+
+## Rules
+
+- Every login failure throws `loginFailed()` from `rate-limit.ts`. Never a specific message.
+- Session ids are opaque random tokens; only `sha256(secret)` reaches the database.
+- Absolute and idle expiry are evaluated **independently**. Activity never moves the ceiling.
+- PKCE is mandatory on every provider. A missing verifier fails the callback.
+- Recovery codes, verification tokens and api keys are hashed at rest and single-use.
+- Guards assert on the actor. They never evaluate a policy.
+
+## Adapter seam
+
+`AuthAdapter` (`adapter.ts`) is the only persistence interface. Better Auth binds here — it is
+an adapter implementation, not a dependency of this package.
+
+| Driver | Use |
+|---|---|
+| `BuiltinAdapter` | Postgres via `@ultimat3/db`; takes an injected `DbClient` |
+| `MemoryAdapter` | `x new` before a database exists, and every test in this package |
+| your own | implement `AuthAdapter`; DDL in `tables.ts` shows what the columns mean |
+
+```bash
+x db gen "auth tables"     # emits AUTH_TABLES into a migration
+```
+
+## Cookie
+
+`__Host-x_session`, set by `sessionCookie(token, policy)`.
+
+| Attribute | Attack it closes |
+|---|---|
+| `HttpOnly` | XSS reading `document.cookie` and exfiltrating the session |
+| `Secure` | a network attacker lifting it off a plaintext request |
+| `SameSite=Lax` | CSRF — the cookie is not attached to cross-site POSTs |
+| `__Host-` + `Path=/` + no `Domain` | a sibling subdomain overwriting it (session fixation) |
+| `Max-Age` | a client keeping it past the server's absolute ceiling |
+
+## OAuth
+
+Two calls: one to leave, one to come back. Provider configs are pure data — importing
+`oauth.ts` performs no network I/O and reads no env.
+
+```ts
+// GET /auth/oauth/:provider — redirect, keeping nothing on the server
+export async function GET(request: Request): Promise<Response> {
+  const handshake = beginOAuth({ provider: 'github', clientId, redirectUri });
+  return new Response(null, {
+    status: 302,
+    headers: { location: handshake.authorizeUrl, 'set-cookie': handshakeCookie(handshake) },
+  });
+}
+```
+
+```ts
+// GET /auth/oauth/:provider/callback — a separate request; the cookie is all that crossed
+export async function GET(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  const { cookie } = await completeOAuthLogin(auth, {
+    handshake: readHandshakeCookie(request, 'github'),
+    callback: { state: url.searchParams.get('state') ?? '', code: url.searchParams.get('code') ?? '' },
+  });
+  const headers = new Headers({ location: '/' });
+  // Both, always: a code is single-use, so the handshake that authorised it must not outlive it.
+  headers.append('set-cookie', cookie);
+  headers.append('set-cookie', clearHandshakeCookie('github'));
+  return new Response(null, { status: 302, headers });
+}
+```
+
+The handshake carries `state`, `nonce` and the PKCE verifier across two requests, so it needs a
+home. `handshakeCookie` is that home — sealed with `SESSION_SECRET`, `HttpOnly; Secure;
+SameSite=Lax` under a `__Host-` name, and expired against the server's clock rather than the
+client's copy of `Max-Age`. `sealHandshake` / `openHandshake` are the same codec without the
+cookie, for an app that would rather keep it server-side.
+
+**One cookie per provider:** `handshakeCookieName(provider)` → `__Host-x_oauth_github`. A browser
+is one cookie jar and a user is allowed two tabs, so a single shared name means the `google`
+redirect overwrites a `github` handshake still in flight — and the github callback then opens
+google's and fails `X_OAUTH_STATE_INVALID` for a reason no restart clears. `handshakeCookie` takes
+the name off `handshake.provider`, `clearHandshakeCookie(provider)` clears only that provider's,
+and `readHandshakeCookie(request, provider)` reads only that provider's. Pass `{ name }` to
+override all three at once.
+
+| Refused | Because |
+|---|---|
+| a handshake with no signature, or one signed with another secret | a browser that can mint a handshake can pair its own code with someone else's session |
+| a `github` handshake opened on the `google` callback | `openHandshake(sealed, provider)` requires the provider, so it cannot be forgotten |
+| a handshake older than `DEFAULT_HANDSHAKE_TTL_MS` (10 min) | a client may ignore `Max-Age`; the server's clock decides |
+| a callback with no handshake cookie | there is nothing to check `state` against |
+| a cookie value that is not valid percent-encoding | the header is the client's; the raw value reaches the signature check and fails it, never a bare `URIError` |
+
+| Provider | PKCE | id token | Env |
+|---|---|---|---|
+| `github` | S256 | — profile + verified-emails call | `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` |
+| `google` | S256 | required, nonce-bound | `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` |
+| `apple` | S256 | required, nonce-bound | `APPLE_CLIENT_ID` / `APPLE_CLIENT_SECRET` |
+
+Apple alone rejects a static secret: `APPLE_CLIENT_SECRET` must hold the ES256 client-secret
+JWT signed with the `.p8` key, which Apple expires every six months.
+
+| Step | Does | Fails with |
+|---|---|---|
+| `handshakeCookie` / `readHandshakeCookie` | seals the handshake onto the redirect, opens it on the callback | `X_OAUTH_STATE_INVALID`, `X_ENV_MISSING` |
+| `exchangeOAuthCode` | POSTs the code + PKCE verifier, verifies the id token | `X_OAUTH_EXCHANGE_FAILED`, `X_OAUTH_TOKEN_INVALID` |
+| `oauthProfile` | id-token claims, else userinfo → one normalised identity | `X_OAUTH_EXCHANGE_FAILED` |
+| `signInWithOAuth` | links the account, applies MFA, mints the session | `X_UNAUTHENTICATED`, `X_MFA_REQUIRED` |
+
+- PKCE's verifier travels only in the exchange — it proves the code belongs to the browser
+  that started the flow.
+- `state` is checked before anything reaches the network; `nonce` is checked inside the id
+  token, because that is where the code flow actually carries it.
+- GitHub reports a bad, reused or expired code as **HTTP 200 with an `error` field**. Trusting
+  the status alone there mints a session from a failed exchange.
+- An address is only linked to an existing account when **both** sides verified it. Otherwise
+  whoever registered the address first inherits the login.
+
+## API keys — how an agent authenticates
+
+`ult_<env>_<id>_<secret>`. The plaintext is shown once; the row holds `sha256(secret)` and is
+looked up by the non-secret id.
+
+```ts
+const { plaintext, record } = issueApiKey({ env: 'prod', scopes: ['post:publish'], orgId });
+await auth.adapter.putApiKey(record);
+const actor = apiKeyActor(await verifyApiKey(auth.adapter, plaintext));  // kind: 'agent'
+```
+
+An api key's scopes become **exactly** the agent actor's scopes — never the owning user's roles.
+
+## Errors
+
+| Code | When |
+|---|---|
+| `X_UNAUTHENTICATED` | no actor, unknown session, or any failed credential path |
+| `X_SESSION_EXPIRED` | idle or absolute expiry, named in `cause` |
+| `X_MFA_REQUIRED` | password proven, second factor outstanding |
+| `X_OAUTH_STATE_INVALID` | state, nonce or PKCE verifier did not match |
+| `X_OAUTH_EXCHANGE_FAILED` | the provider refused the exchange, or returned no usable identity |
+| `X_OAUTH_TOKEN_INVALID` | the id token failed its issuer, audience or expiry check |
+| `X_PASSWORD_WEAK` | strength check rejected the password |
+| `X_ACCOUNT_LOCKED` | per-ip or per-account bucket is inside its lockout |
+| `X_API_KEY_INVALID` | key unknown, revoked, expired or wrong |
+| `X_ENV_MISSING` | `oauthCredentials()` found no client id or secret for an enabled provider |
+| `X_NOT_IMPLEMENTED` | an `AuthAdapter` refused a method (`authNotImplemented(feature, fix)`), or lost a write it accepted — `emailVerifiedNotStored(provider, userId)` when `updateUser` drops the OAuth verified stamp |
+
+```bash
+bun test packages/auth
+bun run --filter @ultimat3/auth typecheck
+```

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ultimat3/auth",
+  "version": "1.0.0",
+  "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/auth"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/db": "1.0.0",
+    "@ultimat3/schema": "1.0.0"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,157 @@
+// Single responsibility: the persistence seam. `AuthAdapter` is the one interface auth talks
+// to, split into per-concern stores so a test (or a caller) can satisfy just the slice it uses.
+// Better Auth binds here — it is an adapter implementation, not a dependency. The blessed
+// default is `BuiltinAdapter` in `builtin-adapter.ts`; the DDL it expects is in `tables.ts`.
+
+export interface AuthUser {
+  readonly id: string;
+  readonly email: string;
+  readonly emailVerifiedAt: Date | null;
+  /** `null` for an OAuth-only account. Never a plaintext password. */
+  readonly passwordHash: string | null;
+  readonly orgId: string | null;
+  /** Authz roles (`editor`), expanded to permissions by `@ultimat3/policy`. */
+  readonly roles: readonly string[];
+  /** Direct grants that bypass roles. Rare; used by break-glass accounts. */
+  readonly permissions: readonly string[];
+  /** Base32 TOTP secret, or `null` when MFA is not enrolled. */
+  readonly mfaSecret: string | null;
+  readonly recoveryCodeHashes: readonly string[];
+  readonly disabledAt: Date | null;
+  readonly createdAt: Date;
+}
+
+export interface CreateUserInput {
+  readonly id: string;
+  readonly email: string;
+  readonly passwordHash: string | null;
+  readonly orgId: string | null;
+  readonly roles: readonly string[];
+  readonly createdAt: Date;
+}
+
+export interface UserPatch {
+  readonly passwordHash?: string | null | undefined;
+  readonly emailVerifiedAt?: Date | null | undefined;
+  readonly mfaSecret?: string | null | undefined;
+  readonly recoveryCodeHashes?: readonly string[] | undefined;
+  readonly disabledAt?: Date | null | undefined;
+  readonly roles?: readonly string[] | undefined;
+}
+
+export interface UserStore {
+  findUserByEmail(email: string): Promise<AuthUser | null>;
+  findUserById(id: string): Promise<AuthUser | null>;
+  createUser(input: CreateUserInput): Promise<AuthUser>;
+  updateUser(id: string, patch: UserPatch): Promise<AuthUser | null>;
+}
+
+export interface AuthSession {
+  /** Public, non-secret lookup key. The secret half of the cookie never reaches the row. */
+  readonly id: string;
+  readonly userId: string;
+  /** SHA-256 of the token secret. A DB dump is not a session-hijack kit. */
+  readonly tokenHash: string;
+  readonly createdAt: Date;
+  /** Hard ceiling, never extended by activity. */
+  readonly absoluteExpiresAt: Date;
+  /** Moves on every request; `idleTtlMs` is measured from here. */
+  readonly lastSeenAt: Date;
+  readonly ip: string | null;
+  readonly userAgent: string | null;
+  readonly mfaSatisfied: boolean;
+}
+
+export interface SessionPatch {
+  readonly lastSeenAt?: Date | undefined;
+  readonly ip?: string | null | undefined;
+  readonly userAgent?: string | null | undefined;
+  readonly mfaSatisfied?: boolean | undefined;
+}
+
+export interface SessionStore {
+  getSession(id: string): Promise<AuthSession | null>;
+  createSession(session: AuthSession): Promise<AuthSession>;
+  updateSession(id: string, patch: SessionPatch): Promise<AuthSession | null>;
+  deleteSession(id: string): Promise<boolean>;
+  /** Returns how many were killed — the "sign out everywhere else" number shown to the user. */
+  deleteOtherSessions(userId: string, keepSessionId: string): Promise<number>;
+  listSessions(userId: string): Promise<readonly AuthSession[]>;
+}
+
+export interface AuthAccount {
+  readonly id: string;
+  readonly userId: string;
+  readonly provider: string;
+  readonly providerAccountId: string;
+  readonly accessToken: string | null;
+  readonly refreshToken: string | null;
+  readonly expiresAt: Date | null;
+  readonly createdAt: Date;
+}
+
+export interface AccountStore {
+  linkAccount(account: AuthAccount): Promise<AuthAccount>;
+  findAccount(provider: string, providerAccountId: string): Promise<AuthAccount | null>;
+  listAccounts(userId: string): Promise<readonly AuthAccount[]>;
+}
+
+export interface AuthVerification {
+  readonly id: string;
+  /** `email-verify` | `password-reset` — see `verify.ts`. */
+  readonly purpose: string;
+  /** The email address the token was issued for. */
+  readonly identifier: string;
+  readonly tokenHash: string;
+  readonly expiresAt: Date;
+  readonly consumedAt: Date | null;
+  readonly createdAt: Date;
+}
+
+export interface VerificationStore {
+  /** Upsert on `(purpose, identifier)` — issuing a new token invalidates the previous one. */
+  putVerification(record: AuthVerification): Promise<void>;
+  /**
+   * Read **and consume** in one atomic step. Single-use is a storage guarantee, not a
+   * caller convention: two concurrent redemptions must not both see an unconsumed row.
+   */
+  takeVerification(purpose: string, identifier: string): Promise<AuthVerification | null>;
+}
+
+export interface AuthApiKeyRecord {
+  /** The non-secret half of the token; the lookup key. */
+  readonly id: string;
+  /** `ult_<env>_<id>` — safe to display, safe to log. */
+  readonly prefix: string;
+  readonly keyHash: string;
+  readonly userId: string | null;
+  readonly orgId: string | null;
+  /** Exactly the scopes the agent actor gets. Never widened at resolve time. */
+  readonly scopes: readonly string[];
+  readonly lastUsedAt: Date | null;
+  readonly expiresAt: Date | null;
+  readonly revokedAt: Date | null;
+  readonly createdAt: Date;
+}
+
+export interface ApiKeyStore {
+  putApiKey(record: AuthApiKeyRecord): Promise<AuthApiKeyRecord>;
+  findApiKeyById(id: string): Promise<AuthApiKeyRecord | null>;
+  listApiKeys(ownerId: string): Promise<readonly AuthApiKeyRecord[]>;
+  touchApiKey(id: string, at: Date): Promise<void>;
+  revokeApiKey(id: string, at: Date): Promise<boolean>;
+}
+
+/**
+ * The full seam. One blessed implementation ships (`BuiltinAdapter`); Better Auth, or any
+ * other identity backend, binds by implementing this and nothing else changes upstream.
+ */
+export interface AuthAdapter
+  extends UserStore,
+    SessionStore,
+    AccountStore,
+    VerificationStore,
+    ApiKeyStore {
+  /** Shown by `x auth doctor --json` so the driver in use is never a guess. */
+  readonly name: string;
+}

package/src/api-keys.ts

@@ -0,0 +1,141 @@
+// Single responsibility: machine credentials. This is how an agent — an MCP client driving a
+// generated Ultimate app — authenticates: it presents a key, the key resolves to an
+// `agentActor` carrying exactly the key's scopes, and it goes through the same policy
+// evaluation a human does. The plaintext is shown once; only its SHA-256 is ever stored, and
+// lookup happens by the non-secret id so the secret never appears in a query, an index or a log.
+
+import { type Clock, randomHex, systemClock } from '@ultimat3/core';
+import type { ApiKeyStore, AuthApiKeyRecord } from './adapter';
+import { apiKeyInvalid } from './errors';
+import type { PolicyActor } from './policy-bridge';
+import { actorFromApiKey } from './policy-bridge';
+import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
+
+export const API_KEY_NAMESPACE = 'ult';
+
+/** `ult_<env>_<id>_<secret>` — the first three segments are the displayable prefix. */
+export const API_KEY_PREFIX_SEGMENTS = 3;
+
+export interface ParsedApiKey {
+  readonly env: string;
+  readonly id: string;
+  readonly prefix: string;
+  readonly secret: string;
+}
+
+export function apiKeyPrefix(env: string, id: string): string {
+  return `${API_KEY_NAMESPACE}_${env}_${id}`;
+}
+
+/**
+ * Split on `_` with a limit: the secret is base64url and may itself contain `_`, so the tail
+ * is rejoined rather than assumed to be a single segment.
+ */
+export function parseApiKey(plaintext: string): ParsedApiKey | null {
+  const parts = plaintext.split('_');
+  if (parts.length <= API_KEY_PREFIX_SEGMENTS) return null;
+  const [namespace, env, id] = parts;
+  if (namespace !== API_KEY_NAMESPACE || env === undefined || id === undefined) return null;
+  if (env.length === 0 || id.length === 0) return null;
+  const secret = parts.slice(API_KEY_PREFIX_SEGMENTS).join('_');
+  if (secret.length === 0) return null;
+  return { env, id, prefix: apiKeyPrefix(env, id), secret };
+}
+
+export interface IssueApiKeyInput {
+  /** `dev` | `stage` | `prod` — visible in the token so a leaked key is triageable at a glance. */
+  readonly env: string;
+  readonly scopes: readonly string[];
+  readonly userId?: string | null | undefined;
+  readonly orgId?: string | null | undefined;
+  readonly expiresAt?: Date | null | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+export interface IssuedApiKey {
+  /** Shown once. Nothing in `record` can reproduce it. */
+  readonly plaintext: string;
+  readonly record: AuthApiKeyRecord;
+}
+
+export function issueApiKey(input: IssueApiKeyInput): IssuedApiKey {
+  const clock = input.clock ?? systemClock;
+  // Hex, not base64url: the id sits between two `_` delimiters and must not contain one.
+  const id = randomHex(8);
+  const secret = randomToken(32);
+  const plaintext = `${apiKeyPrefix(input.env, id)}_${secret}`;
+  return {
+    plaintext,
+    record: {
+      id,
+      prefix: apiKeyPrefix(input.env, id),
+      keyHash: sha256Hex(secret),
+      userId: input.userId ?? null,
+      orgId: input.orgId ?? null,
+      scopes: [...input.scopes],
+      lastUsedAt: null,
+      expiresAt: input.expiresAt ?? null,
+      revokedAt: null,
+      createdAt: clock.now(),
+    },
+  };
+}
+
+/**
+ * Every rejection — malformed, unknown, revoked, expired, wrong secret — throws the same
+ * `X_API_KEY_INVALID`. A caller that can tell "revoked" from "unknown" can enumerate ids.
+ */
+export async function verifyApiKey(
+  store: ApiKeyStore,
+  plaintext: string,
+  clock: Clock = systemClock,
+): Promise<AuthApiKeyRecord> {
+  const parsed = parseApiKey(plaintext);
+  if (parsed === null) throw apiKeyInvalid();
+  const record = await store.findApiKeyById(parsed.id);
+  if (record === null) throw apiKeyInvalid();
+  if (record.revokedAt !== null) throw apiKeyInvalid();
+  const now = clock.now();
+  if (record.expiresAt !== null && now.getTime() >= record.expiresAt.getTime()) {
+    throw apiKeyInvalid();
+  }
+  if (!timingSafeEqual(sha256Hex(parsed.secret), record.keyHash)) throw apiKeyInvalid();
+  await store.touchApiKey(record.id, now);
+  return record;
+}
+
+export async function revokeApiKey(
+  store: ApiKeyStore,
+  id: string,
+  clock: Clock = systemClock,
+): Promise<boolean> {
+  return await store.revokeApiKey(id, clock.now());
+}
+
+/** The agent actor for a verified key. Scopes in, scopes out — nothing is added. */
+export function apiKeyActor(record: AuthApiKeyRecord): PolicyActor {
+  return actorFromApiKey(record);
+}
+
+/** Safe to render in a dashboard or return from an MCP tool: no hash, no secret. */
+export interface ApiKeySummary {
+  readonly id: string;
+  readonly prefix: string;
+  readonly scopes: readonly string[];
+  readonly lastUsedAt: Date | null;
+  readonly expiresAt: Date | null;
+  readonly revokedAt: Date | null;
+  readonly createdAt: Date;
+}
+
+export function describeApiKey(record: AuthApiKeyRecord): ApiKeySummary {
+  return {
+    id: record.id,
+    prefix: record.prefix,
+    scopes: record.scopes,
+    lastUsedAt: record.lastUsedAt,
+    expiresAt: record.expiresAt,
+    revokedAt: record.revokedAt,
+    createdAt: record.createdAt,
+  };
+}