@seasonkoh/webaz 0.1.26 → 0.1.28

package/dist/runtime/agent-grant-scopes.js

@@ -0,0 +1,128 @@
+/**
+ * RFC-020 PR-B — agent delegation grant scope taxonomy (pure, no I/O).
+ *
+ * Source of truth: docs/rfcs/RFC-020-agent-delegation-grants.md §3.1/§3.2 and the
+ * companion docs/rfcs/RFC-020-implementation-plan.md §3. Importable by the PWA
+ * grant routes, the (future) MCP `webaz_pair` consumer, and tests — no DB, no env.
+ *
+ * THREE tiers. In PR-B a grant may carry ONLY safe scopes:
+ *   - SAFE: grantable now (server-enforced constraints, no per-action Passkey).
+ *   - RISK: **default hard-reject** in PR-B. They are NOT yet Passkey-gated at the
+ *     route level (place_order / order actions / refunds / wallet ops are plain
+ *     auth() paths today), so a grant must never carry them until each money/state
+ *     route adds a real Passkey gate in its own dedicated, money-path-aware PR.
+ *   - NEVER_DELEGABLE: server hard-reject forever — no grant may EVER carry these
+ *     (funds movement, key/Passkey changes, grant self-escalation, admin/governance,
+ *     account creation/deletion, access-control). "Do it at webaz.xyz with a live
+ *     Passkey."
+ *
+ * PR-B touches NO payment/wallet/order/refund/escrow/commission/fund/tokenomics
+ * code; it only classifies scope strings and gates what a grant may be issued for.
+ */
+/** Grantable now — read/draft surfaces; benign or constraint-bounded. */
+export const SAFE_SCOPES = [
+    'read_public',
+    'profile_read',
+    'search',
+    'list_product_draft',
+    'product_publish_request',
+    'draft_order',
+];
+/**
+ * Real actions that WILL require a live Passkey each time — but are NOT yet gated
+ * at the route level. Default hard-reject in PR-B (see module header).
+ */
+export const RISK_SCOPES = [
+    'place_order',
+    'order_accept',
+    'order_ship',
+    'order_status',
+    'wallet',
+    'payout',
+    'refund',
+    'arbitrate',
+    'vote',
+    'claim_verify',
+];
+/** Never carried by any grant — server hard-reject, independent of UI. */
+export const NEVER_DELEGABLE_SCOPES = [
+    'withdraw',
+    'transfer',
+    'convert',
+    'deposit',
+    'fund_move',
+    'api_key_create',
+    'api_key_rotate',
+    'api_key_reveal',
+    'passkey_change',
+    'grant_escalate',
+    'account_delete',
+    'access_control_change',
+    'admin',
+    'protocol_param',
+    'create_live_account',
+];
+const SAFE = new Set(SAFE_SCOPES);
+const RISK = new Set(RISK_SCOPES);
+const NEVER = new Set(NEVER_DELEGABLE_SCOPES);
+export function classifyScope(capability) {
+    if (NEVER.has(capability))
+        return 'never_delegable';
+    if (RISK.has(capability))
+        return 'risk';
+    if (SAFE.has(capability))
+        return 'safe';
+    return 'unknown';
+}
+/**
+ * Validate the capabilities requested for a grant. PR-B policy: a grant is issuable
+ * ONLY if every requested capability is SAFE. Any risk / never-delegable / unknown
+ * scope rejects the whole request (fail-closed). The error_code distinguishes the
+ * permanent never-delegable wall from the "not enabled yet" risk wall.
+ */
+export function validateRequestedCapabilities(caps) {
+    const safe = [];
+    const rejected = [];
+    if (!Array.isArray(caps) || caps.length === 0) {
+        return { ok: false, safe, rejected: [{ capability: '(none)', tier: 'unknown', error_code: 'NO_CAPABILITIES', reason: 'at least one capability is required' }] };
+    }
+    for (const c of caps) {
+        const cap = c?.capability;
+        const tier = typeof cap === 'string' ? classifyScope(cap) : 'unknown';
+        switch (tier) {
+            case 'safe':
+                safe.push(cap);
+                break;
+            case 'risk':
+                rejected.push({ capability: String(cap), tier, error_code: 'RISK_SCOPE_NOT_ENABLED', reason: 'risk scope is not delegable yet — the owning money/state route must add a live-Passkey gate first (RFC-020 §3.1)' });
+                break;
+            case 'never_delegable':
+                rejected.push({ capability: String(cap), tier, error_code: 'NEVER_DELEGABLE', reason: 'never-delegable iron-rule action — must be done by the human at webaz.xyz with a live Passkey (RFC-020 §3.2)' });
+                break;
+            default:
+                rejected.push({ capability: String(cap ?? '(missing)'), tier: 'unknown', error_code: 'UNKNOWN_SCOPE', reason: 'unknown capability — not in the safe scope set' });
+        }
+    }
+    return { ok: rejected.length === 0, safe, rejected };
+}
+/** A grant authorizes nothing unless it is active and unexpired. `nowIso` for testability. */
+export function grantIsActive(grant, nowIso) {
+    if (!grant)
+        return false;
+    if (grant.status !== 'active')
+        return false;
+    if (grant.revoked_at)
+        return false;
+    if (!grant.expires_at)
+        return false;
+    return grant.expires_at > nowIso;
+}
+/** Short-lived bearer policy for SAFE scopes (RFC-020 bearer-first; PoP before risk/longer). */
+export const GRANT_TTL_DEFAULT_SEC = 3600; // 1h
+export const GRANT_TTL_MAX_SEC = 24 * 3600; // 24h cap — short-lived only
+export function clampTtlSeconds(requested) {
+    const n = Number(requested);
+    if (!Number.isFinite(n) || n <= 0)
+        return GRANT_TTL_DEFAULT_SEC;
+    return Math.min(Math.floor(n), GRANT_TTL_MAX_SEC);
+}

package/dist/runtime/agent-grant-verifier.js

@@ -0,0 +1,67 @@
+/**
+ * RFC-020 PR-C2a — delegation grant verifier (server-side consumption foundation).
+ *
+ * This is the ONLY sanctioned path that turns a `gtk_*` bearer into an authorization,
+ * and it is **opt-in per route + per required SAFE scope** — it is NOT global auth.
+ * A grant token is never equivalent to a human session or a permanent api_key:
+ *   - global auth()/api_key resolution is untouched and never accepts gtk_* tokens;
+ *   - this verifier returns a NARROW principal (grant_id, human_id, agent_label,
+ *     capability) — not a user/session — and only for an explicitly-required SAFE scope.
+ *
+ * PR-C2a does NOT enable any risk scope. The required scope MUST be SAFE; the verifier
+ * refuses to authorize anything else (defense in depth), and a grant only passes if it
+ * actually carries that exact safe capability and is active/unexpired/unrevoked.
+ *
+ * Reads via the RFC-016 async seam (dbOne) so PWA and (later, PR-C2b) MCP share it.
+ * NO money/order/wallet/refund logic.
+ */
+import { createHash } from 'node:crypto';
+import { dbOne } from '../layer0-foundation/L0-1-database/db.js';
+import { classifyScope, grantIsActive } from './agent-grant-scopes.js';
+function parseCaps(json) {
+    try {
+        const v = JSON.parse(String(json));
+        return Array.isArray(v) ? v : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Verify a `gtk_*` bearer for an EXPLICIT required SAFE scope. Returns a narrow grant
+ * principal on success, or a typed failure. `nowIso` injectable for tests.
+ */
+export async function verifyGrantToken(bearer, requiredScope, nowIso = new Date().toISOString()) {
+    // Programming guard: an opt-in route must require a SAFE scope. Risk / never-delegable /
+    // unknown can NEVER be satisfied by a grant — fail closed regardless of the token.
+    if (classifyScope(requiredScope) !== 'safe') {
+        return { ok: false, status: 500, error_code: 'SCOPE_NOT_SAFE', error: `requiredScope "${requiredScope}" is not a safe scope; grants can only ever authorize safe scopes` };
+    }
+    if (!bearer || !bearer.startsWith('gtk_')) {
+        return { ok: false, status: 401, error_code: 'GRANT_TOKEN_REQUIRED', error: 'a gtk_* delegation grant bearer is required for this scope' };
+    }
+    const tokenHash = createHash('sha256').update(bearer).digest('hex');
+    const row = await dbOne('SELECT grant_id, human_id, agent_label, capabilities, status, expires_at, revoked_at FROM agent_delegation_grants WHERE token_hash = ?', [tokenHash]);
+    if (!row) {
+        return { ok: false, status: 401, error_code: 'GRANT_NOT_FOUND', error: 'delegation grant not found for this token' };
+    }
+    if (!grantIsActive(row, nowIso)) {
+        return { ok: false, status: 403, error_code: 'GRANT_INACTIVE', error: 'delegation grant is revoked, expired, or inactive', grant_id: row.grant_id, human_id: row.human_id };
+    }
+    // The grant is only as valid as its accountable human. Mirror auth(): the subject must still
+    // exist and not be suspended (user_moderation.suspended) — else a grant minted before an admin
+    // suspension would outlive it. Fail closed.
+    const subject = await dbOne('SELECT u.id AS id, m.suspended AS suspended FROM users u LEFT JOIN user_moderation m ON m.user_id = u.id WHERE u.id = ?', [row.human_id]);
+    if (!subject) {
+        return { ok: false, status: 403, error_code: 'GRANT_SUBJECT_INACTIVE', error: 'grant subject (human) no longer exists', grant_id: row.grant_id, human_id: row.human_id };
+    }
+    if (subject.suspended) {
+        return { ok: false, status: 403, error_code: 'GRANT_SUBJECT_INACTIVE', error: 'grant subject (human) is suspended', grant_id: row.grant_id, human_id: row.human_id };
+    }
+    const caps = parseCaps(row.capabilities);
+    const holds = caps.some(c => c?.capability === requiredScope && classifyScope(String(c.capability)) === 'safe');
+    if (!holds) {
+        return { ok: false, status: 403, error_code: 'SCOPE_NOT_GRANTED', error: `grant does not carry the required safe scope "${requiredScope}"`, grant_id: row.grant_id, human_id: row.human_id };
+    }
+    return { ok: true, principal: { grant_id: row.grant_id, human_id: row.human_id, agent_label: row.agent_label, capability: requiredScope } };
+}

package/dist/runtime/agent-pairing.js

@@ -0,0 +1,60 @@
+/**
+ * RFC-020 PR-C1 — pairing primitives (pure, no DB/network).
+ *
+ * PKCE (RFC 7636, S256) + short one-time code / id generation + TTL. Shared by the
+ * PWA pairing routes and the MCP `webaz_pair` tool so both compute the challenge the
+ * same way. PR-C1 is pairing + credential delivery ONLY — no scope enforcement
+ * (that is PR-C2), no money/order/wallet code.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+/** base64url (no padding). */
+function b64url(buf) {
+    return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** PKCE code_verifier — high-entropy URL-safe string (RFC 7636 §4.1). */
+export function generateCodeVerifier() {
+    return b64url(randomBytes(48)); // ~64 chars
+}
+/** PKCE S256 challenge = base64url(sha256(verifier)). */
+export function pkceChallengeS256(verifier) {
+    return b64url(createHash('sha256').update(verifier).digest());
+}
+/** Constant-shape PKCE check: the verifier must hash to the stored challenge. */
+export function verifyPkceS256(verifier, challenge) {
+    if (typeof verifier !== 'string' || typeof challenge !== 'string' || !verifier || !challenge)
+        return false;
+    const computed = pkceChallengeS256(verifier);
+    // length-guarded compare (challenges are fixed-length base64url of a sha256)
+    if (computed.length !== challenge.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < computed.length; i++)
+        diff |= computed.charCodeAt(i) ^ challenge.charCodeAt(i);
+    return diff === 0;
+}
+const CODE_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'; // Crockford base32 (no I/L/O/U)
+/** Short, human-approvable one-time pairing code. */
+export function generateUserCode(len = 10) {
+    const bytes = randomBytes(len);
+    let out = '';
+    for (let i = 0; i < len; i++)
+        out += CODE_ALPHABET[bytes[i] % CODE_ALPHABET.length];
+    return out;
+}
+/** Pairing session TTL — short by design (RFC-020 §3.6). */
+export const PAIRING_TTL_DEFAULT_SEC = 600; // 10 min to approve + retrieve
+export const PAIRING_TTL_MAX_SEC = 1800; // 30 min cap
+export function clampPairingTtlSeconds(requested) {
+    const n = Number(requested);
+    if (!Number.isFinite(n) || n <= 0)
+        return PAIRING_TTL_DEFAULT_SEC;
+    return Math.min(Math.floor(n), PAIRING_TTL_MAX_SEC);
+}
+/** A pairing can be approved only while pending + unexpired. */
+export function pairingApprovable(p, nowIso) {
+    return !!p && p.status === 'pending' && !!p.expires_at && p.expires_at > nowIso;
+}
+/** A pairing can be retrieved only while approved, unexpired, and not yet consumed. */
+export function pairingRetrievable(p, nowIso) {
+    return !!p && p.status === 'approved' && !p.consumed_at && !!p.expires_at && p.expires_at > nowIso;
+}

package/dist/runtime/apply-webaz-runtime-schema.js

@@ -0,0 +1,15 @@
+import * as helpers from './webaz-schema-helpers.js';
+export function applyWebazRuntimeSchema(db) {
+    // Call every pure idempotent DDL initializer exported by the shared helpers
+    // module (convention: each is named init*Schema / init*Columns and is a
+    // side-effect-free `(db) => void`). Order-independent: all statements are
+    // CREATE ... IF NOT EXISTS / guarded ALTER, so re-running or reordering is a
+    // no-op. New helpers are picked up automatically — no risk of forgetting one
+    // (which is exactly how the MCP/PWA schemas drifted apart in the first place).
+    for (const [name, fn] of Object.entries(helpers)) {
+        if (name.startsWith('init') && typeof fn === 'function') {
+            ;
+            fn(db);
+        }
+    }
+}