@venturekit/auth 0.0.1 → 0.0.2

package/dist/server/store/postgres.js

@@ -0,0 +1,88 @@
+/**
+ * @venturekit/auth — Postgres VerificationCodeStore
+ *
+ * Production {@link VerificationCodeStore} backing the OTP primitives
+ * ({@link requestVerificationCode} / {@link verifyVerificationCode}).
+ * Talks to the project's primary Postgres database via
+ * `@venturekit/data`'s `query()` — or any `Querier`, so the caller can
+ * enlist code writes in an already-open transaction (pass a
+ * `Transaction`'s `query`; the default is the global connection pool).
+ *
+ * The backing table `vk_verification_codes` is shipped by this package's
+ * `migrations/vk_auth_001_verification_codes.sql` and applied by the
+ * in-VPC migration runner `@venturekit/infra` provisions — so consumers
+ * get the table and this store from the same package.
+ *
+ * `@venturekit/data` is an OPTIONAL peer dependency: importing THIS
+ * module is what opts a project into the Postgres store, so apps on a
+ * different backend (DynamoDB, the in-memory dev store) never load it
+ * and `@venturekit/auth/server` stays storage-agnostic.
+ *
+ * `expires_at` crosses the store boundary as ms-epoch to satisfy
+ * {@link VerificationCodeRecord}'s numeric contract: `to_timestamp` on
+ * write, `EXTRACT(EPOCH …) * 1000` on read.
+ */
+import { query } from '@venturekit/data';
+function rowToRecord(r) {
+    return {
+        channel: r.channel,
+        identifier: r.identifier,
+        codeHash: r.code_hash,
+        expiresAt: Number(r.expires_at),
+        attempts: r.attempts,
+        maxAttempts: r.max_attempts,
+    };
+}
+/**
+ * Build a Postgres-backed {@link VerificationCodeStore} bound to `q`.
+ *
+ * Pass a transaction's `query` (see `beginTransaction` /
+ * `withTransaction` in `@venturekit/data`) to make code writes
+ * participate in an open transaction; omit it to use the global pool.
+ */
+export function createPostgresVerificationCodeStore(q = query) {
+    return {
+        async put({ channel, identifier, codeHash, expiresAt, maxAttempts }) {
+            // Opportunistic sweep of already-expired rows on every write —
+            // keeps the table bounded without a dedicated cron (the migration
+            // ships the `expires_at` index that backs this).
+            await q(`DELETE FROM vk_verification_codes WHERE expires_at < CURRENT_TIMESTAMP`);
+            // Idempotent per the store contract: a re-request overwrites the
+            // outstanding code for this (channel, identifier) and resets the
+            // attempt counter — a fresh code means "let me try again", not
+            // "reset the limit on the old one".
+            await q(`INSERT INTO vk_verification_codes
+           (channel, identifier, code_hash, expires_at, attempts, max_attempts)
+         VALUES ($1, $2, $3, to_timestamp($4 / 1000.0), 0, $5)
+         ON CONFLICT (channel, identifier) DO UPDATE
+            SET code_hash    = EXCLUDED.code_hash,
+                expires_at   = EXCLUDED.expires_at,
+                attempts     = 0,
+                max_attempts = EXCLUDED.max_attempts,
+                created_at   = NOW()`, [channel, identifier, codeHash, expiresAt, maxAttempts]);
+        },
+        async get({ channel, identifier }) {
+            // Return the row as-is, INCLUDING when expired — verifyVerificationCode
+            // performs the expiry check and deletes the row itself.
+            return q(`SELECT channel, identifier, code_hash,
+                (EXTRACT(EPOCH FROM expires_at) * 1000)::bigint AS expires_at,
+                attempts, max_attempts
+           FROM vk_verification_codes
+          WHERE channel = $1 AND identifier = $2
+          LIMIT 1`, [channel, identifier], (rows) => {
+                const r = rows[0];
+                return r ? rowToRecord(r) : undefined;
+            });
+        },
+        async incrementAttempts({ channel, identifier }) {
+            return q(`UPDATE vk_verification_codes
+            SET attempts = attempts + 1
+          WHERE channel = $1 AND identifier = $2
+          RETURNING attempts`, [channel, identifier], (rows) => rows[0]?.attempts ?? 0);
+        },
+        async delete({ channel, identifier }) {
+            await q(`DELETE FROM vk_verification_codes WHERE channel = $1 AND identifier = $2`, [channel, identifier]);
+        },
+    };
+}
+//# sourceMappingURL=postgres.js.map

package/dist/server/store/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../../../src/server/store/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,KAAK,EAAgB,MAAM,kBAAkB,CAAC;AAiBvD,SAAS,WAAW,CAAC,CAAsB;IACzC,OAAO;QACL,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,QAAQ,EAAE,CAAC,CAAC,SAAS;QACrB,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC;QAC/B,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,WAAW,EAAE,CAAC,CAAC,YAAY;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mCAAmC,CACjD,IAAa,KAAK;IAElB,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE;YACjE,+DAA+D;YAC/D,kEAAkE;YAClE,iDAAiD;YACjD,MAAM,CAAC,CACL,wEAAwE,CACzE,CAAC;YACF,iEAAiE;YACjE,iEAAiE;YACjE,+DAA+D;YAC/D,oCAAoC;YACpC,MAAM,CAAC,CACL;;;;;;;;qCAQ6B,EAC7B,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC,CACxD,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE;YAC/B,wEAAwE;YACxE,wDAAwD;YACxD,OAAO,CAAC,CACN;;;;;kBAKU,EACV,CAAC,OAAO,EAAE,UAAU,CAAC,EACrB,CAAC,IAAI,EAAE,EAAE;gBACP,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAA+C,CAAC;gBAChE,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACxC,CAAC,CACF,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE;YAC7C,OAAO,CAAC,CACN;;;6BAGqB,EACrB,CAAC,OAAO,EAAE,UAAU,CAAC,EACrB,CAAC,IAAI,EAAE,EAAE,CACN,IAAI,CAAC,CAAC,CAAsC,EAAE,QAAQ,IAAI,CAAC,CAC/D,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE;YAClC,MAAM,CAAC,CACL,0EAA0E,EAC1E,CAAC,OAAO,EAAE,UAAU,CAAC,CACtB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/server/token-utils.d.ts

@@ -8,8 +8,9 @@
  * treat those responses as fatal, we derive the remaining lifetime
  * from the access token itself.
  *
- * This file intentionally has no `@venturekit/auth/server` surface
- * exposure — it's consumed by `sign-in.ts` and `refresh.ts` only.
+ * `decodeJwtClaims` IS part of the public surface: consumers that
+ * just minted tokens (sign-in, passwordless flows) read profile
+ * claims from the id token without a redundant verify round-trip.
  */
 /** Cognito's default access-token lifetime (1 hour). */
 export declare const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 3600;
@@ -24,4 +25,13 @@ export declare const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 3600;
  * `InitiateAuthCommand`). Use `verifyAndDecode` for untrusted input.
  */
 export declare function deriveExpiresInFromJwt(jwt: string, nowSeconds?: number): number;
+/**
+ * Base64url-decode and JSON.parse a JWT payload. Returns `null` on any
+ * failure — callers fall back to a default.
+ *
+ * Does NOT verify the signature — only use on tokens received
+ * directly from the identity provider (e.g. right after sign-in).
+ * Use `verifyAndDecode` for anything that crossed a trust boundary.
+ */
+export declare function decodeJwtClaims<T extends Record<string, unknown> = Record<string, unknown>>(jwt: string): T | null;
 //# sourceMappingURL=token-utils.d.ts.map

package/dist/server/token-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-utils.d.ts","sourceRoot":"","sources":["../../src/server/token-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wDAAwD;AACxD,eAAO,MAAM,gCAAgC,OAAO,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAAsC,GACjD,MAAM,CAgBR"}
+{"version":3,"file":"token-utils.d.ts","sourceRoot":"","sources":["../../src/server/token-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,wDAAwD;AACxD,eAAO,MAAM,gCAAgC,OAAO,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAAsC,GACjD,MAAM,CAgBR;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzF,GAAG,EAAE,MAAM,GACV,CAAC,GAAG,IAAI,CAYV"}

package/dist/server/token-utils.js

@@ -8,8 +8,9 @@
  * treat those responses as fatal, we derive the remaining lifetime
  * from the access token itself.
  *
- * This file intentionally has no `@venturekit/auth/server` surface
- * exposure — it's consumed by `sign-in.ts` and `refresh.ts` only.
+ * `decodeJwtClaims` IS part of the public surface: consumers that
+ * just minted tokens (sign-in, passwordless flows) read profile
+ * claims from the id token without a redundant verify round-trip.
  */
 /** Cognito's default access-token lifetime (1 hour). */
 export const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 3600;
@@ -24,7 +25,7 @@ export const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 3600;
  * `InitiateAuthCommand`). Use `verifyAndDecode` for untrusted input.
  */
 export function deriveExpiresInFromJwt(jwt, nowSeconds = Math.floor(Date.now() / 1000)) {
-    const payload = decodeJwtPayload(jwt);
+    const payload = decodeJwtClaims(jwt);
     if (!payload)
         return DEFAULT_ACCESS_TOKEN_TTL_SECONDS;
     const exp = typeof payload.exp === 'number' ? payload.exp : undefined;
@@ -42,8 +43,12 @@ export function deriveExpiresInFromJwt(jwt, nowSeconds = Math.floor(Date.now() /
 /**
  * Base64url-decode and JSON.parse a JWT payload. Returns `null` on any
  * failure — callers fall back to a default.
+ *
+ * Does NOT verify the signature — only use on tokens received
+ * directly from the identity provider (e.g. right after sign-in).
+ * Use `verifyAndDecode` for anything that crossed a trust boundary.
  */
-function decodeJwtPayload(jwt) {
+export function decodeJwtClaims(jwt) {
     if (typeof jwt !== 'string' || jwt.length === 0)
         return null;
     const parts = jwt.split('.');

package/dist/server/token-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-utils.js","sourceRoot":"","sources":["../../src/server/token-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wDAAwD;AACxD,MAAM,CAAC,MAAM,gCAAgC,GAAG,IAAI,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAW,EACX,aAAqB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IAElD,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,CAAC,OAAO;QAAE,OAAO,gCAAgC,CAAC;IAEtD,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAEtE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,gCAAgC,CAAC;IAE/D,MAAM,SAAS,GAAG,GAAG,GAAG,UAAU,CAAC;IACnC,IAAI,SAAS,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAEpC,0EAA0E;IAC1E,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,GAAG,GAAG;QAAE,OAAO,GAAG,GAAG,GAAG,CAAC;IAErD,OAAO,gCAAgC,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACrE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAY,CAAC;QAC3C,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,GAA8B,CAAC;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"token-utils.js","sourceRoot":"","sources":["../../src/server/token-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,wDAAwD;AACxD,MAAM,CAAC,MAAM,gCAAgC,GAAG,IAAI,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAW,EACX,aAAqB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IAElD,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,OAAO;QAAE,OAAO,gCAAgC,CAAC;IAEtD,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAEtE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,gCAAgC,CAAC;IAE/D,MAAM,SAAS,GAAG,GAAG,GAAG,UAAU,CAAC;IACnC,IAAI,SAAS,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAEpC,0EAA0E;IAC1E,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,GAAG,GAAG;QAAE,OAAO,GAAG,GAAG,GAAG,CAAC;IAErD,OAAO,gCAAgC,CAAC;AAC1C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAW;IAEX,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACrE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAY,CAAC;QAC3C,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,GAAQ,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturekit/auth",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Authentication and authorization for VentureKit",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,24 +34,33 @@
     "./server": {
       "import": "./dist/server/index.js",
       "types": "./dist/server/index.d.ts"
+    },
+    "./server/store/postgres": {
+      "import": "./dist/server/store/postgres.js",
+      "types": "./dist/server/store/postgres.d.ts"
     }
   },
   "dependencies": {
-    "@venturekit/core": "0.0.1",
+    "@venturekit/core": "0.0.2",
     "@aws-sdk/client-cognito-identity-provider": "^3.1068.0",
     "@aws-sdk/client-secrets-manager": "^3.1068.0",
     "aws-jwt-verify": "^4.0.1"
   },
   "peerDependencies": {
-    "@venturekit/runtime": "0.0.1"
+    "@venturekit/data": "0.0.2",
+    "@venturekit/runtime": "0.0.2"
   },
   "peerDependenciesMeta": {
+    "@venturekit/data": {
+      "optional": true
+    },
     "@venturekit/runtime": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@venturekit/runtime": "0.0.1",
+    "@venturekit/data": "0.0.2",
+    "@venturekit/runtime": "0.0.2",
     "@types/aws-lambda": "^8.10.131",
     "@types/node": "^25.6.0",
     "typescript": "^5.3.0"

package/src/migrations/vk_auth_003_role_scopes.sql

@@ -0,0 +1,43 @@
+-- @venturekit/auth — role → scopes mapping.
+--
+-- The DB is the SOURCE OF TRUTH for which scopes each role grants.
+-- VentureKit ships the STRUCTURE (this migration, applied automatically
+-- with every other package migration); the consuming app ships DATA
+-- migrations to seed its own taxonomy, e.g.:
+--
+--   INSERT INTO vk_role_scopes (role, scope) VALUES
+--     ('member',    'member.verified'),
+--     ('moderator', 'member.verified'),
+--     ('moderator', 'moderation.reports.read')
+--   ON CONFLICT DO NOTHING;
+--
+-- Lives in @venturekit/auth — NOT in a pro package — because a role →
+-- scopes matrix is baseline authorization for ANY app: single-tenant
+-- apps key it by their global user role; multi-tenant apps feed it to
+-- `@venturekit-pro/tenancy`'s scopes middleware
+-- (`createTenantUserScopesMiddleware({ scopesByRole: resolver.lookup })`).
+--
+-- At runtime the mapping is read through `createRoleScopesResolver()`
+-- (cached, TTL-refreshed). Mutations go through `setRoleScopes` /
+-- `grantScopeToRole` / `revokeScopeFromRole`, so apps can build
+-- management UIs on top — changes propagate to warm instances within
+-- the resolver's TTL.
+--
+-- Deliberately GLOBAL (no tenant column): the mapping is the app's
+-- authorization POLICY, not tenant data. Per-tenant overrides, if ever
+-- needed, belong in a separate overlay table so the hot path stays a
+-- single cached full-table read.
+
+CREATE TABLE IF NOT EXISTS vk_role_scopes (
+  role        text        NOT NULL,
+  scope       text        NOT NULL,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (role, scope)
+);
+
+COMMENT ON TABLE vk_role_scopes IS
+  'Role → scope grants. Structure owned by @venturekit/auth; rows owned by the consuming app (seed via app migrations, manage via the role-scopes helpers).';
+
+-- Scope grants are read by role on every request that misses the
+-- resolver cache; the PK already serves (role, scope) lookups and
+-- role-prefix scans.