tr-plugin-auth 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# Auth plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Auth owns encrypted provider credentials, dashboard and collaboration passwords, purpose-bound session signing, passkey storage, and scoped API-key lifecycle. Core adapters require its manifest exports and have no credential implementation fallback.
+
+## Operations
+
+- `total-recall auth status --json`: local configuration inventory; does not certify provider availability.
+- `total-recall auth password set --stdin`: commits the dashboard bcrypt hash and a new signing key to encrypted auth storage; invalidates prior dashboard sessions.
+- `total-recall auth rotate [--collaboration] --json`: explicitly rotates the selected signing key.
+- `total-recall auth secret --help`: credential inventory, verified setup, rekey and deployment projections.
+- `total-recall auth passkey list --json`: registered public credential inventory.
+- `total-recall auth probe --json`: actual endpoint response statuses, not a security certification.
+
+
+Dashboard/step-up/collaboration tokens use HS256 with issuer, purpose-specific audience, bounded expiry and independent collaboration key. Keys remain inside auth. Password mutation does not write security.yml. API keys persist only token hashes; passkey storage contains public authenticator material, not private keys.
+
+Before uninstall, auth verifies and preserves encrypted ciphertext outside the brain. Locked, corrupt, plaintext, conflicting or unmigrated legacy credentials abort teardown. No live credential migration is performed by source changes.
+
+The card displays requested results only. The panel performs browser credential creation plus server verification before reporting registration success. Hardware attestation, provider availability and rotation schedules are never fabricated.
+
+Integration and whole-ecosystem migration remain in progress. Fixture tests do not prove a physical passkey, OAuth provider login or fleet deployment.
+
+## Use it two ways
+
+This plugin is a reusable brick, so a new project does not start from zero.
+
+**Add it to a project (for apps you build and ship).** From the project directory:
+
+```sh
+total-recall plugin vendor ./tr-plugin-auth 
+```
+
+This copies the plugin's source, skills, tests and docs into `bricks/auth` and records it in `tr-bricks.json`. Your project then owns that code: edit it, test it in your own gates, and ship it with no runtime dependency on this plugin or on Total Recall. Combine as many bricks as the project needs. List them with `total-recall plugin bricks`.
+
+**Use it directly with Total Recall (for your own machines and workflow).** Install it with `total-recall plugin install ./tr-plugin-auth` and run `total-recall auth`. Manage its credentials with `total-recall auth secret` and its skills with `total-recall skill`.
+### Google connections and scoped access keys
+
+Google OAuth credentials use the selected auth brain's encrypted store. Configure `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, a registered `GOOGLE_REDIRECT_URI` ending in `/auth/google/callback`, and `GOOGLE_ALLOWED_EMAILS` (comma-separated dashboard account allowlist) through `auth secret set --stdin`. The CLI's connection link opens the server initiation endpoint so the browser receives an HttpOnly state cookie. Callbacks require browser-bound one-use state, PKCE and a verified authorized identity; failed profile lookup never creates a placeholder session.
+
+`auth google accounts --json` returns secret-free connection metadata. `auth google refresh <subject> --json` refreshes expired access while preserving an existing refresh token when Google omits it; revoked grants require reconnection. `auth google disconnect <subject> --json` confirms provider revocation before dropping credentials. Transient failures retain the connection. OAuth API tokens and signed dashboard sessions have separate lifetimes; refreshing Google access does not extend the dashboard login session.
+
+`auth key issue <name> --scopes memory:read --role reader --kind api_key --expires <ISO-date> --json` issues a token once. `auth key list`, `revoke <id>`, `usage <id>`, `roles`, and `role-set <name> --scopes <csv>` manage its lifecycle. Empty permissions grant nothing; malformed scopes fail explicitly. Role policies bound scopes on every request. HTTP issuance cannot exceed its issuer's permissions or expiry, and only administrators can edit role policies. Metadata retains hashes, prefixes and usage; raw tokens never enter canonical SSSS records. The `pat` and `api_key` kinds share the Bearer authentication protocol for this application's API; they do not manufacture third-party provider keys.
+
+Google lifecycle metadata, role policies, key registries and request audit ledgers use the native host SSSS state contract. Ciphertext remains in the auth-owned opaque resource adapter. This source requires the updated native host contract; older published hosts need an explicit compatible update. Fixture tests do not certify live Google consent or deployed CRM consumer adapters.
+
+Native-only state: new installations use validated SSSS records and the shared auth owner. Legacy imports and compatibility fallback formats are not supported.

package/cli.mjs

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+/**
+ * Auth CLI Handler
+ * Executed via: npx total-recall auth <subcommand>
+ * Subcommands: status, passkey, google, probe, session
+ * Exit codes: 0 ok, 1 usage/error, 2 not configured
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function resolveTrPath() {
+  const localTr = path.join(process.cwd(), 'bin', 'total-recall.mjs');
+  if (fs.existsSync(localTr)) return localTr;
+  const parentTr = path.join(process.cwd(), '..', 'total-recall', 'bin', 'total-recall.mjs');
+  if (fs.existsSync(parentTr)) return parentTr;
+  return null;
+}
+
+async function resolveSecret(key) {
+  const { getSecret, defaultBrainDir } = await import('./src/secrets-store.mjs');
+  const result = await getSecret(process.env.TR_SECRETS_BRAIN || defaultBrainDir(), key, { actor: 'auth-cli', action: 'use' });
+  return result.found ? result.value : null;
+}
+
+function resolveBrainDir() {
+  return process.env.TR_SECRETS_BRAIN || process.env.TR_BRAIN || path.join(process.env.HOME || '', '.agent', 'skills', 'total-recall');
+}
+
+async function listStoredPasskeys() {
+  const { listPasskeys } = await import('./src/webauthn-store.mjs');
+  return listPasskeys(resolveBrainDir());
+}
+
+async function handleStatus(json) {
+  const passkeys = await listStoredPasskeys();
+  const googleClientId = await resolveSecret('GOOGLE_CLIENT_ID');
+  const googleClientSecret = await resolveSecret('GOOGLE_CLIENT_SECRET');
+  const googleReady = Boolean(googleClientId && googleClientSecret);
+
+  const status = {
+    passkey: {
+      enabled: true,
+      registered_count: passkeys.length,
+      credentials: passkeys.map((p) => ({
+        id: p.id,
+        label: p.label || 'Passkey',
+        created_at: p.created_at || null,
+        backed_up: Boolean(p.backedUp),
+      })),
+    },
+    google_oauth2: {
+      configured: googleReady,
+      client_id: googleClientId ? `${googleClientId.slice(0, 12)}…` : null,
+      has_secret: Boolean(googleClientSecret),
+    },
+    system: {
+      status: 'local-configuration-read',
+      providerVerified: false,
+      brain_dir: resolveBrainDir(),
+    },
+  };
+
+  if (json) {
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+
+  console.log('Total Recall Auth Engine');
+  console.log('───────────────────────────────────────────────────────');
+  console.log(`Passkey WebAuthn : Enabled (${passkeys.length} credential${passkeys.length === 1 ? '' : 's'})`);
+  if (passkeys.length > 0) {
+    for (const p of passkeys) {
+      console.log(`  • [${p.label || 'Passkey'}] ID: ${p.id.slice(0, 16)}… (${p.created_at || 'unknown date'})`);
+    }
+  } else {
+    console.log('  • No passkeys registered in the vault');
+  }
+
+  console.log(`Google OAuth2    : ${googleReady ? 'Configured' : 'Not Configured'}`);
+  if (googleClientId) {
+    console.log(`  • Client ID    : ${googleClientId.slice(0, 16)}…`);
+  } else {
+    console.log('  • Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in the secrets store');
+  }
+}
+
+async function handlePasskey(subArgs, json) {
+  const passkeys = await listStoredPasskeys();
+  const action = subArgs[0] || 'list';
+
+  if (action === 'list') {
+    if (json) {
+      console.log(JSON.stringify({ count: passkeys.length, passkeys }, null, 2));
+      return;
+    }
+    console.log(`Registered Passkeys: ${passkeys.length}`);
+    for (const p of passkeys) {
+      console.log(`• ${p.label || 'Passkey'} [${p.id}]`);
+    }
+    return;
+  }
+
+  if (action === 'status') {
+    const res = { enabled: true, count: passkeys.length };
+    if (json) {
+      console.log(JSON.stringify(res, null, 2));
+    } else {
+      console.log(`Passkey status: ${passkeys.length > 0 ? 'Active' : 'No credentials registered'}`);
+    }
+    return;
+  }
+
+  console.error(`Unknown passkey action: ${action}`);
+  process.exitCode = 1;
+}
+
+async function handleGoogle(subArgs, json) {
+  const { createGoogleOAuth } = await import('./src/google-oauth.mjs');
+  const google = createGoogleOAuth({ brainDir: resolveBrainDir() });
+  const action = subArgs[0] || 'status';
+  if (action === 'accounts') { console.log(JSON.stringify({ accounts: google.status() })); return; }
+  if (action === 'refresh' || action === 'disconnect') {
+    if (!subArgs[1]) throw new Error('Google account identifier required');
+    if (action === 'refresh') { await google.access(subArgs[1]); console.log(JSON.stringify({ accounts: google.status() })); }
+    else console.log(JSON.stringify(await google.disconnect(subArgs[1])));
+    return;
+  }
+  if (!['status', 'connect'].includes(action)) throw new Error('Use google status|connect|accounts|refresh|disconnect');
+  let cfg;
+  try { cfg = google.config(); } catch {
+    console.log(JSON.stringify({ configured: false, error: 'Configure GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_REDIRECT_URI in auth' })); process.exitCode = 2; return;
+  }
+  // Browser initiation sets its own HttpOnly state cookie; never manufacture a state-less consent URL in the CLI.
+  const authUrl = new URL('/auth/google', cfg.redirectUri).href;
+  const out = { configured: true, client_id: `${cfg.clientId.slice(0, 12)}…`, redirect_uri: cfg.redirectUri, auth_url: authUrl };
+  console.log(json ? JSON.stringify(out) : `Open sign-in: ${authUrl}`);
+}
+
+async function handleProbe(json) {
+  const host = process.env.TR_HOST || 'http://localhost:3000';
+  const endpoints = ['/auth/status', '/auth/providers', '/health'];
+  const results = [];
+
+  for (const ep of endpoints) {
+    const url = `${host}${ep}`;
+    const startTime = Date.now();
+    try {
+      const res = await fetch(url);
+      const latencyMs = Date.now() - startTime;
+      results.push({
+        endpoint: ep,
+        url,
+        status: res.status,
+        ok: res.ok,
+        latency_ms: latencyMs,
+      });
+    } catch (err) {
+      results.push({
+        endpoint: ep,
+        url,
+        status: 0,
+        ok: false,
+        error: err.message,
+        latency_ms: Date.now() - startTime,
+      });
+    }
+  }
+
+  const allOk = results.every((r) => r.ok && r.status === 200);
+
+  if (json) {
+    console.log(JSON.stringify({ success: allOk, probes: results }, null, 2));
+  } else {
+    console.log('Auth Endpoint 200 Probes:');
+    for (const r of results) {
+      const badge = r.status === 200 ? ' 200 OK' : ` ${r.status || 'CONN_ERR'}`;
+      console.log(`  ${badge} ${r.endpoint.padEnd(20)} (${r.latency_ms}ms)`);
+    }
+  }
+  if (!allOk) process.exitCode = 1;
+}
+
+async function handleSession(json) {
+  const brain = resolveBrainDir();
+  const secretExists = Boolean(await resolveSecret('SESSION_SECRET'));
+
+  const payload = {
+    session_secret_configured: secretExists,
+    mode: 'secure-http-only-cookie',
+    ttl_hours: 24,
+  };
+
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log('Session Security Status:');
+    console.log(`  Session Secret : ${secretExists ? 'Present' : 'Not generated yet'}`);
+    console.log('  Cookie Policy  : HttpOnly, SameSite=Lax');
+    console.log('  Token Format   : Signed JWT');
+  }
+}
+
+async function handleSecret(subArgs, json) {
+  const { default: secretCli } = await import('./src/cli-secret.mjs');
+  const forwarded = json && !subArgs.includes('--json') ? [...subArgs, '--json'] : subArgs;
+  await secretCli(forwarded);
+}
+
+async function handleAudit(json) {
+  const brain = resolveBrainDir();
+  const webauthnPath = path.join(brain, 'config', 'webauthn.json');
+  const findings = [];
+
+  // Check 1: WebAuthn file permissions
+  if (fs.existsSync(webauthnPath)) {
+    try {
+      const stats = fs.statSync(webauthnPath);
+      const mode = (stats.mode & 0o777).toString(8);
+      if (mode !== '600' && mode !== '400') {
+        findings.push({
+          target: 'webauthn.json',
+          severity: 'HIGH',
+          message: `Permissions mode is ${mode}, expected 0600 (owner read/write only)`,
+        });
+      }
+    } catch {
+      // stat check fallback
+    }
+  }
+
+  // Check 2: Session secret entropy
+  const sessionSecret = await resolveSecret('SESSION_SECRET');
+  if (!sessionSecret) {
+    findings.push({
+      target: 'SESSION_SECRET',
+      severity: 'MEDIUM',
+      message: 'SESSION_SECRET not stored in secrets store; session signing unavailable; initialize through auth',
+    });
+  } else if (sessionSecret.length < 32) {
+    findings.push({
+      target: 'SESSION_SECRET',
+      severity: 'HIGH',
+      message: 'SESSION_SECRET length is under 32 characters (insufficient entropy)',
+    });
+  }
+
+  // Check 3: Google OAuth2 paired credentials
+  const gId = await resolveSecret('GOOGLE_CLIENT_ID');
+  const gSec = await resolveSecret('GOOGLE_CLIENT_SECRET');
+  if (gId && !gSec) {
+    findings.push({
+      target: 'GOOGLE_CLIENT_SECRET',
+      severity: 'CRITICAL',
+      message: 'GOOGLE_CLIENT_ID is set but GOOGLE_CLIENT_SECRET is missing',
+    });
+  }
+
+  const passed = findings.filter((f) => f.severity === 'CRITICAL' || f.severity === 'HIGH').length === 0;
+  const report = {
+    audit: 'Total Recall Auth Security Baseline',
+    passed,
+    findings_count: findings.length,
+    findings,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log('Total Recall Auth Security Audit Report');
+    console.log('───────────────────────────────────────────────────────');
+    console.log(`Status : ${passed ? ' PASSED' : ' ISSUES DETECTED'} (${findings.length} findings)`);
+    if (findings.length === 0) {
+      console.log('All auth credentials, WebAuthn stores, and session configurations pass baseline checks.');
+    } else {
+      for (const f of findings) {
+        console.log(`  [${f.severity}] ${f.target}: ${f.message}`);
+      }
+    }
+  }
+  if (!passed) process.exitCode = 1;
+}
+
+async function handleRotate(subArgs, json) {
+  const { createSessionCredentials } = await import('./src/session-credentials.mjs');
+  const { defaultBrainDir } = await import('./src/secrets-store.mjs');
+  const purpose = subArgs.includes('--collaboration') ? 'collaboration' : 'dashboard';
+  const result = createSessionCredentials({ brainDir: process.env.TR_SECRETS_BRAIN || defaultBrainDir() }).rotateSession(purpose);
+  console.log(json ? JSON.stringify(result) : 'Auth signing credential rotated; existing sessions are invalidated.');
+}
+async function handlePassword(args, json) {
+  if (args[0] !== 'set' || !args.includes('--stdin') || args.slice(1).some(value => !['--stdin', '--force-reset'].includes(value))) throw new Error('Use auth password set --stdin');
+  const chunks = []; let size = 0;
+  for await (const chunk of process.stdin) { size += chunk.length; if (size > 8192) throw new Error('Password input exceeds limit'); chunks.push(chunk); }
+  const password = Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
+  const { createSessionCredentials } = await import('./src/session-credentials.mjs');
+  const result = await createSessionCredentials({ brainDir: resolveBrainDir() }).setDashboardPassword(password, { forcePasswordReset: args.includes('--force-reset') });
+  console.log(json ? JSON.stringify(result) : 'Dashboard credential saved through auth; existing sessions invalidated.');
+}
+
+export async function run(argv = []) {
+  let args = Array.isArray(argv) ? [...argv] : [];
+  if (args[0] && args[0].endsWith('node')) args = args.slice(1);
+  if (args[0] && (args[0].endsWith('cli.mjs') || args[0].endsWith('total-recall') || args[0] === 'auth')) args = args.slice(1);
+  if (args[0] === 'auth') args = args.slice(1);
+
+  const isJson = args.includes('--json') || args.includes('-j');
+  const filteredArgs = args.filter((a) => a !== '--json' && a !== '-j');
+  const command = filteredArgs[0] || 'status';
+  const rest = filteredArgs.slice(1);
+
+  switch (command) {
+    case 'status':
+      await handleStatus(isJson);
+      break;
+    case 'audit':
+      await handleAudit(isJson);
+      break;
+    case 'rotate':
+      await handleRotate(rest, isJson);
+      break;
+    case 'password':
+      await handlePassword(rest, isJson);
+      break;
+    case 'passkey':
+      await handlePasskey(rest, isJson);
+      break;
+    case 'key': {
+      const { createKeyStore } = await import('./src/access-keys.mjs');
+      const store = createKeyStore({ brainDir: resolveBrainDir() });
+      const [action = 'list', id] = rest;
+      const flag = name => { const at = rest.indexOf(name); return at < 0 ? undefined : rest[at + 1]; };
+      let result;
+      if (action === 'list') result = store.loadKeys().map(({ token_hash, ...key }) => key);
+      else if (action === 'issue') result = store.issueKey(id, { scopes: flag('--scopes')?.split(','), role: flag('--role'), kind: flag('--kind'), expires_at: flag('--expires') });
+      else if (action === 'revoke') result = store.revokeKey(id);
+      else if (action === 'usage') result = store.listKeyUsage(id);
+      else if (action === 'roles') result = store.loadRoles();
+      else if (action === 'role-set') result = store.setRole(id, flag('--scopes')?.split(','));
+      else throw new Error('Use auth key list|issue <name> --scopes <csv> [--role role] [--expires date]|revoke <id>|usage [id]|roles|role-set <name> --scopes <csv>');
+      console.log(JSON.stringify(result)); break;
+    }
+    case 'google':
+      await handleGoogle(rest, isJson);
+      break;
+    case 'probe':
+      await handleProbe(isJson);
+      break;
+    case 'session':
+      await handleSession(isJson);
+      break;
+    case 'secret':
+    case 'secrets':
+      await handleSecret(rest, isJson);
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log('Usage: total-recall auth <command> [--json]');
+      console.log('Commands:');
+      console.log('  status   Show auth providers and security status');
+      console.log('  audit    Audit permissions, session secrets, and credential integrity');
+      console.log('  rotate   Generate and securely rotate SESSION_SECRET in store');
+      console.log('  passkey  List or verify registered WebAuthn passkeys');
+      console.log('  google status|connect|accounts|refresh <id>|disconnect <id>   Encrypted OAuth lifecycle');
+      console.log('  probe    Execute HTTP 200 probe across auth endpoints');
+      console.log('  session  Inspect session secret and security flags');
+      console.log('  key list|issue|revoke|usage|roles|role-set   Scoped tokens and role policies');
+      console.log('  secret   Inspect and manage Total Recall secrets store keys');
+      console.log('  password set --stdin [--force-reset]   Set encrypted dashboard credential');
+      break;
+    default:
+      console.error(`Unknown subcommand: ${command}. Run 'total-recall auth --help' for guidance.`);
+      process.exitCode = 1;
+  }
+}
+
+export default run;
+
+if (process.argv[1]?.endsWith('cli.mjs')) {
+  run(process.argv).catch(() => { console.error(JSON.stringify({ error: 'Auth operation failed; verify store access and arguments. No success established.' })); process.exitCode = 1; });
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "tr-plugin-auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "White-label Total Recall auth plugin: Passkey biometric FIDO2 and Google OAuth2 authentication.",
+  "type": "module",
+  "main": "cli.mjs",
+  "scripts": {
+    "test": "node --test test/auth.test.mjs && vitest run --exclude '**/auth.test.mjs'"
+  },
+  "keywords": [
+    "total-recall-plugin",
+    "auth",
+    "passkeys",
+    "oauth2",
+    "google"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "vitest": "^5.0.3",
+    "supertest": "^7.2.2"
+  },
+  "dependencies": {
+    "total-recall-brain": "^3.39.1",
+    "yaml": "^2.9.0",
+    "bcrypt": "^6.0.0",
+    "jsonwebtoken": "^9.0.3",
+    "express-rate-limit": "^8.5.1",
+    "@simplewebauthn/server": "^13.3.2",
+    "express": "^5.2.1"
+  },
+  "files": [
+    "cli.mjs",
+    "plugin.json",
+    "README.md",
+    "src/",
+    "!src/**/*.spec.mjs",
+    "ui/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}