tr-plugin-auth 0.0.0-stage → 1.0.0

package/plugin.json

@@ -0,0 +1,266 @@
+{
+  "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
+  "id": "auth",
+  "name": "Auth & Secrets",
+  "version": "1.0.0",
+  "description": "Hardware WebAuthn biometric FIDO2 passkeys, OAuth session security, and access control.",
+  "author": "Total Recall contributors",
+  "license": "MIT",
+  "use_cases": [
+    "security",
+    "developer-tools"
+  ],
+  "branding": {
+    "name": "Auth & Secrets",
+    "color": "#10b981",
+    "badge": "FIDO2 Vault",
+    "font": "chivo-mono"
+  },
+  "card_face": {
+    "skin": "winamp-classic",
+    "theme": "vibrant",
+    "headline": "Passkey & Google OAuth2 Authentication Engine",
+    "primary_color": "#6366f1",
+    "secondary_color": "#312e81",
+    "accent_color": "#818cf8",
+    "touch_layout": "comfortable",
+    "interactive": true,
+    "quick_actions": [
+      {
+        "subcommand": "status",
+        "label": "STATUS"
+      },
+      {
+        "subcommand": "audit",
+        "label": "AUDIT"
+      },
+      {
+        "subcommand": "passkey",
+        "label": "PASSKEY"
+      },
+      {
+        "subcommand": "google",
+        "label": "GOOGLE"
+      },
+      {
+        "subcommand": "rotate",
+        "label": "ROTATE"
+      },
+      {
+        "subcommand": "probe",
+        "label": "CHECK ENDPOINT"
+      }
+    ]
+  },
+  "secrets": [
+    {
+      "key": "GOOGLE_CLIENT_ID",
+      "description": "Google OAuth2 Client ID from Google Cloud Console",
+      "required": false
+    },
+    {
+      "key": "GOOGLE_CLIENT_SECRET",
+      "description": "Google OAuth2 Client Secret",
+      "required": false
+    },
+    {
+      "key": "SESSION_SECRET",
+      "description": "Auth-owned encrypted session signing key; explicit auth rotation or password setup required",
+      "required": false
+    },
+    {
+      "key": "COLLAB_SESSION_SECRET",
+      "required": false,
+      "description": "Auth-owned isolated collaboration token signing key"
+    },
+    {
+      "key": "GOOGLE_REDIRECT_URI",
+      "description": "Trusted registered OAuth callback URI ending in /auth/google/callback",
+      "required": false
+    },
+    {
+      "key": "GOOGLE_ALLOWED_EMAILS",
+      "description": "Explicit dashboard Google account allowlist (comma-separated verified emails)",
+      "required": false
+    }
+  ],
+  "cli": {
+    "command": "auth",
+    "handler": "./cli.mjs",
+    "subcommands": [
+      {
+        "name": "status",
+        "description": "Display auth system status and active providers",
+        "effect": "read"
+      },
+      {
+        "name": "audit",
+        "description": "Audit permissions, session secrets, and credential integrity",
+        "effect": "read"
+      },
+      {
+        "name": "rotate",
+        "description": "Generate and securely rotate SESSION_SECRET in store",
+        "effect": "destructive"
+      },
+      {
+        "name": "passkey",
+        "description": "Manage FIDO2 WebAuthn passkeys",
+        "effect": "write"
+      },
+      {
+        "name": "google",
+        "description": "Google OAuth status, connect, accounts, refresh and verified disconnect",
+        "effect": "write"
+      },
+      {
+        "name": "probe",
+        "description": "Run HTTP 200 health verification probe",
+        "effect": "read"
+      },
+      {
+        "name": "session",
+        "description": "Inspect active session tokens",
+        "effect": "read"
+      },
+      {
+        "name": "secret",
+        "description": "Manage and inspect auth secrets in the Total Recall store",
+        "effect": "write"
+      },
+      {
+        "name": "password",
+        "description": "Set dashboard password through encrypted auth store: set --stdin [--force-reset]",
+        "effect": "write"
+      },
+      {
+        "name": "key",
+        "description": "Issue, list, revoke and audit scoped tokens; inspect and update role policy",
+        "effect": "write",
+        "sensitive_output": true
+      }
+    ]
+  },
+  "ui": {
+    "elements": [
+      {
+        "id": "card",
+        "kind": "card",
+        "tag": "tr-auth-card",
+        "module": "ui/card.js",
+        "description": "Gatepass Card Face"
+      },
+      {
+        "id": "panel",
+        "kind": "panel",
+        "tag": "tr-auth-panel",
+        "module": "ui/panel.js",
+        "description": "Auth Management Panel"
+      }
+    ]
+  },
+  "configuration": {
+    "fields": [
+      {
+        "name": "googleCallbackUrl",
+        "label": "Google Redirect URI",
+        "type": "string",
+        "default": "/auth/google/callback"
+      },
+      {
+        "name": "passkeyRpName",
+        "label": "Relying Party Name",
+        "type": "string",
+        "default": "Total Recall"
+      },
+      {
+        "name": "sessionTtlHours",
+        "label": "Session Duration (Hours)",
+        "type": "number",
+        "default": 168
+      }
+    ]
+  },
+  "deploy": {
+    "targets": [
+      "ssss-app",
+      "nextjs",
+      "react",
+      "flask"
+    ],
+    "required_ssss_version": ">=0.9.3",
+    "access_grants": [
+      "auth:session:verify",
+      "ssss:vault:read",
+      "ssss:vault:write",
+      "ssss:events:append"
+    ]
+  },
+  "ssss_schemas": {
+    "categories": [
+      {
+        "name": "auth-sessions",
+        "description": "Authenticated user sessions and biometric credentials",
+        "node_type": "memory"
+      },
+      {
+        "name": "auth-tokens",
+        "description": "OAuth2 and passkey authentication tokens",
+        "node_type": "memory"
+      }
+    ]
+  },
+  "auth": {
+    "plugin": "auth",
+    "methods": [
+      "passkey",
+      "google-oauth2"
+    ],
+    "session_verification": true
+  },
+  "runtime": {
+    "modules": {
+      "secrets-store": "src/secrets-store.mjs",
+      "secrets-gateway": "src/secrets-gateway.mjs",
+      "secrets-keychain": "src/secrets-keychain.mjs",
+      "secrets-env-diff": "src/secrets-env-diff.mjs",
+      "secrets-env-export": "src/secrets-env-export.mjs",
+      "secrets-rotate": "src/secrets-rotate.mjs",
+      "secrets-rekey": "src/secrets-rekey.mjs",
+      "secrets-remote-deploy": "src/secrets-remote-deploy.mjs",
+      "secrets-sync": "src/secrets-sync.mjs",
+      "env-import": "src/env-import.mjs",
+      "crypto": "src/crypto.mjs",
+      "provider-catalog": "src/provider-catalog.mjs",
+      "provider-account-sync": "src/provider-account-sync.mjs",
+      "provider-rotation-recipes": "src/provider-rotation-recipes.mjs",
+      "rotation-capability": "src/rotation-capability.mjs",
+      "browser-session": "src/browser-session.mjs",
+      "secret-integration-research": "src/secret-integration-research.mjs",
+      "configuration": "src/configuration.mjs",
+      "server-auth": "src/server-auth.mjs",
+      "session-credentials": "src/session-credentials.mjs",
+      "commands": "cli.mjs",
+      "credential-preservation": "src/credential-preservation.mjs",
+      "access-keys": "src/access-keys.mjs",
+      "webauthn-store": "src/webauthn-store.mjs",
+      "auth-router": "src/routes/auth.mjs",
+      "webauthn-router": "src/routes/webauthn.mjs",
+      "secrets-router": "src/routes/secrets.mjs",
+      "runtime-credentials": "src/runtime-credentials.mjs",
+      "keys-router": "src/routes/keys.mjs",
+      "google-oauth": "src/google-oauth.mjs"
+    },
+    "routers": [
+      "src/routes/secrets-runtime.mjs"
+    ]
+  },
+  "status": {
+    "command": "status",
+    "refresh_seconds": 60
+  },
+  "distribution": {
+    "tier": "official",
+    "license": "open"
+  }
+}

package/src/access-keys.mjs

@@ -0,0 +1,225 @@
+/**
+ * API Key Lifecycle Manager
+ *
+ * Manages Personal Access Tokens (PATs) in validated native SSSS records.
+ *
+ * Schema:
+ *   { id, name, token_hash, token_prefix, scopes, expires_at, created_at, last_used_at, hit_count, revoked }
+ */
+
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { authState, assertNoSecretValues, appendAuthMetadata, authLedger } from './metadata-state.mjs';
+
+export function createKeyStore({ brainDir }) {
+if (!brainDir) throw new Error('Explicit auth key store required');
+const BRAIN_DIR = brainDir;
+const KEYS_FILE = path.join(BRAIN_DIR, 'config', 'keys.jsonl');
+const state = authState(KEYS_FILE);
+const roleState = authState(path.join(BRAIN_DIR, 'config/key-roles.json'));
+const usageFile = path.join(BRAIN_DIR, 'logs/key-usage.jsonl');
+
+const ALL_SCOPES = '*';
+
+const KNOWN_SCOPES = [
+  ALL_SCOPES,
+  'chat:read',
+  'chat:write',
+  'models:read',
+  'instructions:read',
+  'ssss:read',
+  'ssss:write',
+  'memory:read',
+  'memory:write',
+  'memory:recompile',
+  'sandbox:run',
+  'tts:use',
+  'tasks:read',
+  'tasks:write',
+  'files:read',
+  'config:read',
+  'config:write',
+  'keys:read',
+  'keys:write',
+  'health:read'
+];
+
+function hashToken(token) {
+  return crypto.createHash('sha256').update(token, 'utf8').digest('hex');
+}
+
+function safeEqualHex(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  if (!/^[a-f0-9]{64}$/i.test(a) || !/^[a-f0-9]{64}$/i.test(b)) return false;
+  return crypto.timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+}
+
+function normalizeKey(raw) {
+  const key = { ...raw };
+  // name must always be a string — guard against bad issueKey({ name }) calls
+  if (key.name && typeof key.name === 'object') {
+    key.name = String(key.name.name || key.name.label || 'Unnamed Key');
+  } else if (typeof key.name !== 'string' || !key.name.trim()) {
+    key.name = key.name == null ? 'Unnamed Key' : String(key.name);
+  }
+  if (Object.hasOwn(key, 'token')) throw new Error('Raw credentials are not a native key record');
+  key.scopes = normalizeScopes(key.scopes);
+  key.expires_at = key.expires_at || null;
+  key.hit_count = key.hit_count || 0;
+  key.revoked = !!key.revoked;
+  return key;
+}
+
+function normalizeScopes(scopes) {
+  if (scopes == null) return [];
+  if (!Array.isArray(scopes) || scopes.some(scope => typeof scope !== 'string' || !(scope === ALL_SCOPES || /^[a-z][a-z0-9-]*:(\*|[a-z][a-z0-9-]*)$/.test(scope)))) throw new Error('Invalid scopes; no permissions granted');
+  return [...new Set(scopes)];
+}
+
+function loadRoles() {
+  const roles = roleState.read({ admin: ['*'], reader: KNOWN_SCOPES.filter(scope => scope.endsWith(':read')), operator: ['memory:read', 'memory:write', 'ssss:read', 'tasks:read', 'tasks:write'] });
+  if (!roles || typeof roles !== 'object' || Array.isArray(roles)) throw new Error('Invalid key role policy');
+  for (const [name, scopes] of Object.entries(roles)) { if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) throw new Error('Invalid role name'); normalizeScopes(scopes); }
+  return roles;
+}
+function setRole(name, scopes) {
+  const roles = loadRoles();
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) throw new Error('Invalid role name');
+  roles[name] = normalizeScopes(scopes); roleState.write(roles); return { name, scopes: roles[name] };
+}
+function scopeMatches(scopes, required) {
+  return scopes.includes('*') || scopes.includes(required) || scopes.includes(`${String(required).split(':')[0]}:*`);
+}
+
+function isExpiredKey(key, now = new Date()) {
+  if (!key?.expires_at) return false;
+  const expires = new Date(key.expires_at);
+  if (Number.isNaN(expires.getTime())) return true;
+  return expires.getTime() <= now.getTime();
+}
+
+function keyHasScope(key, requiredScope) {
+  if (!key || key.revoked || isExpiredKey(key)) return false;
+  if (!requiredScope) return true;
+  const scopes = normalizeScopes(key?.scopes);
+  const role = key.role ? loadRoles()[key.role] : null;
+  return scopeMatches(scopes, requiredScope) && (!key.role || (Array.isArray(role) && scopeMatches(role, requiredScope)));
+}
+
+function keyHasAnyScope(key, requiredScopes = []) {
+  if (!requiredScopes.length) return true;
+  return requiredScopes.some(scope => keyHasScope(key, scope));
+}
+
+function loadKeys() {
+  const keys = state.read([]);
+  if (!Array.isArray(keys)) throw new Error('Invalid PAT registry');
+  keys.forEach(assertNoSecretValues);
+  return keys.map(normalizeKey);
+}
+
+function saveKeys(keys) {
+  const sanitized = keys.map((key) => {
+    const { token, ...rest } = normalizeKey(key);
+    return rest;
+  });
+  sanitized.forEach(assertNoSecretValues);
+  state.write(sanitized);
+}
+
+/**
+ * Issue a PAT.
+ * @param {string|object} nameOrOpts - display name, or { name, scopes, expires_at }
+ * @param {object} [options]
+ */
+function issueKey(nameOrOpts, options = {}) {
+  let name = nameOrOpts;
+  let opts = options;
+  // Accept issueKey({ name, scopes }) form safely
+  if (nameOrOpts && typeof nameOrOpts === 'object' && !Array.isArray(nameOrOpts)) {
+    name = nameOrOpts.name || nameOrOpts.label || 'Unnamed Key';
+    opts = {
+      scopes: nameOrOpts.scopes ?? options.scopes,
+      expires_at: nameOrOpts.expires_at ?? nameOrOpts.expiresAt ?? options.expires_at ?? options.expiresAt,
+      role: nameOrOpts.role ?? options.role,
+      issuer: options.issuer,
+      kind: nameOrOpts.kind ?? options.kind,
+    };
+  }
+  if (typeof name !== 'string' || !name.trim()) {
+    name = 'Unnamed Key';
+  }
+
+  const scopes = normalizeScopes(opts.scopes);
+  if (opts.role && !Object.hasOwn(loadRoles(), opts.role)) throw new Error('Unknown key role');
+  if (opts.kind && !['pat', 'api_key'].includes(opts.kind)) throw new Error('Invalid key kind');
+  const issuer = opts.issuer;
+  if (issuer && (!keyHasScope(issuer, 'keys:write') || scopes.some(scope => !keyHasScope(issuer, scope)))) throw new Error('Cannot issue privileges beyond the issuer');
+  const expiresAt = opts.expires_at || opts.expiresAt || null;
+  if (expiresAt && !Number.isFinite(Date.parse(expiresAt))) throw new Error('Invalid key expiry');
+  if (issuer?.expires_at && (!expiresAt || Date.parse(expiresAt) > Date.parse(issuer.expires_at))) throw new Error('Issued key cannot outlive its issuer');
+  const keys = loadKeys();
+  const token = `tr_${crypto.randomBytes(32).toString('base64url')}`;
+  const key = {
+    id: crypto.randomUUID(),
+    name: name.trim(),
+    token_hash: hashToken(token),
+    token_prefix: token.slice(0, 8),
+    scopes,
+    role: opts.role || null,
+    issued_by: issuer?.id || 'local-operator',
+    kind: opts.kind || 'pat',
+    expires_at: expiresAt,
+    created_at: new Date().toISOString(),
+    last_used_at: null,
+    hit_count: 0,
+    revoked: false,
+  };
+  keys.push(key);
+  saveKeys(keys);
+  return { ...key, token };
+}
+
+function revokeKey(id) {
+  const keys = loadKeys();
+  const key = keys.find(k => k.id === id);
+  if (!key) return null;
+  key.revoked = true;
+  saveKeys(keys);
+  return key;
+}
+
+function recordKeyUsage(token, details = {}) {
+  const keys = loadKeys();
+  const tokenHash = hashToken(token);
+  const key = keys.find(k => safeEqualHex(k.token_hash, tokenHash) && !k.revoked && !isExpiredKey(k));
+  if (!key) return false;
+  key.hit_count = (key.hit_count || 0) + 1;
+  key.last_used_at = new Date().toISOString();
+  saveKeys(keys);
+  appendAuthMetadata(usageFile, { key_id: key.id, timestamp: key.last_used_at, action: 'request',
+    ...(typeof details.method === 'string' ? { method: details.method } : {}),
+    ...(typeof details.path === 'string' ? { path: details.path.split('?')[0] } : {}),
+    ...(Number.isInteger(details.status) ? { status: details.status } : {}) });
+  return true;
+}
+function listKeyUsage(id) { return authLedger(usageFile).filter(row => !id || row.key_id === id); }
+function recordKeyOutcome(id, { method, path: requestPath, status } = {}) {
+  if (typeof id !== 'string' || !Number.isInteger(status) || status < 100 || status > 599) throw new Error('Invalid request outcome');
+  appendAuthMetadata(usageFile, { action: 'request_outcome', key_id: id, timestamp: new Date().toISOString(),
+    method: typeof method === 'string' ? method : '', path: typeof requestPath === 'string' ? requestPath.split('?')[0] : '', status });
+}
+
+function isValidToken(token) {
+  return !!findValidKeyByToken(token);
+}
+
+function findValidKeyByToken(token) {
+  if (!token || token === 'local') return null;
+  const tokenHash = hashToken(token);
+  const keys = loadKeys();
+  return keys.find(k => safeEqualHex(k.token_hash, tokenHash) && !k.revoked && !isExpiredKey(k)) || null;
+}
+
+return { ALL_SCOPES, KNOWN_SCOPES, normalizeScopes, isExpiredKey, keyHasScope, keyHasAnyScope, loadKeys, issueKey, revokeKey, recordKeyUsage, isValidToken, findValidKeyByToken, loadRoles, setRole, listKeyUsage, recordKeyOutcome };
+}

package/src/agent-dir.mjs

@@ -0,0 +1,3 @@
+import { importHostModule } from './host-runtime.mjs';
+const hostModule = await importHostModule('src/cli/agent-dir.mjs');
+export const { parseLayerFlag, getGlobalAgentDir, getGlobalBrainDir, detectProjectBrain, resolveAgentDir, resolveBrainDir, getBothBrains, defaultLayerForCategory } = hostModule;