@oxy.so/core 1.0.0

package/src/server/auth.ts

@@ -0,0 +1,271 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import type { OxyServices } from '../OxyServices';
+import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
+
+export { OXY_SERVICE_ENVIRONMENTS };
+export type { OxyServiceEnvironment };
+
+export interface OxyRequestUser {
+  id: string;
+  _id?: string;
+  username?: string;
+  email?: string;
+  avatar?: string;
+  [key: string]: unknown;
+}
+
+export interface OxyServiceAppContext {
+  appId: string;
+  appName: string;
+  scopes: string[];
+  credentialId: string;
+  /**
+   * The Oxy account that owns `appId` and is financially responsible for it.
+   * Read off the VERIFIED service-token claim set — never a user id, and never
+   * the delegated `X-Oxy-User-Id` (ADR 0007).
+   */
+  ownerAccountId: string;
+  environment: OxyServiceEnvironment;
+}
+
+export interface OxyServiceActingAsContext {
+  userId: string;
+  scopes: string[];
+}
+
+export interface OxyAuthRequest extends Request {
+  userId?: string | null;
+  user?: OxyRequestUser | null;
+  accessToken?: string;
+  sessionId?: string | null;
+  serviceApp?: OxyServiceAppContext;
+  serviceActingAs?: OxyServiceActingAsContext;
+}
+
+export interface OxyAuthenticatedRequest extends OxyAuthRequest {
+  userId: string;
+  user: OxyRequestUser;
+}
+
+export interface OxyAuthMiddlewareOptions {
+  /**
+   * Options forwarded to `oxy.auth()`.
+   * `optional` is forced to `true` by the composed helpers so route guards can
+   * produce one consistent 401 shape.
+   */
+  auth?: Parameters<OxyServices['auth']>[0];
+}
+
+function normalizeId(value: string | null | undefined): string | null {
+  const normalized = value?.trim();
+  return normalized && normalized.length > 0 ? normalized : null;
+}
+
+function ensureUser(req: OxyAuthRequest, userId: string): OxyRequestUser {
+  const existing = req.user;
+  if (existing) {
+    const user = {
+      ...existing,
+      id: normalizeId(existing.id) ?? normalizeId(existing._id) ?? userId,
+    };
+    req.user = user;
+    return user;
+  }
+
+  const user = { id: userId };
+  req.user = user;
+  return user;
+}
+
+export function getOxyUserId(req: Request): string | null {
+  const authReq = req as OxyAuthRequest;
+  return (
+    normalizeId(authReq.userId) ??
+    normalizeId(authReq.user?.id) ??
+    normalizeId(authReq.user?._id)
+  );
+}
+
+export function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest {
+  return getOxyUserId(req) !== null;
+}
+
+/**
+ * The principal a request is CHARGED to, and the identifiers a receipt needs.
+ *
+ * Every field is read from the verified service-token claim set. It is an
+ * OBJECT, not a string, and that is the point: `getOxyUserId` returns a
+ * `string | null`, so a delegated end-user id cannot be passed anywhere an
+ * `OxyBillingPrincipal` is expected. The confusion ADR 0007 forbids —
+ * attributing spend to the person a service is acting for rather than to the
+ * service's own account — stops being a code-review question and becomes a
+ * compile error.
+ *
+ * `scopes` are the effective scopes minted into the token (credential ∩
+ * application). Nothing re-intersects them here.
+ */
+export interface OxyBillingPrincipal {
+  /** `applications.owner_account_id` — the financially responsible account. */
+  readonly accountId: string;
+  readonly applicationId: string;
+  readonly credentialId: string;
+  readonly environment: OxyServiceEnvironment;
+  readonly scopes: readonly string[];
+}
+
+/**
+ * The full canonical attribution of ADR 0007 for a request: the billing
+ * principal PLUS the optional delegated end user.
+ *
+ * `delegatedUserId` is named for what it is. It answers "on whose behalf" and
+ * is absent for a machine credential acting for itself — its absence is normal,
+ * and nothing may synthesize one. If removing it would change what any account
+ * is charged, the code reading it is wrong.
+ */
+export interface OxyRequestAttribution extends OxyBillingPrincipal {
+  readonly delegatedUserId: string | null;
+}
+
+/**
+ * The billing principal of a request, or `null` when the request carries no
+ * verified service principal (an ordinary user session is not a billable
+ * machine principal — its account is resolved from the account graph, not from
+ * a token claim).
+ *
+ * Reads `req.serviceApp` and NOTHING else: not `req.userId`, not `req.user`,
+ * not `req.serviceActingAs`. That exclusivity is the invariant this function
+ * exists to hold, and `serviceTokenAttribution.test.ts` mutation-tests it.
+ *
+ * **It answers for the SERVICE-TOKEN lane only.** The API's machine-credential
+ * lane (`oxy_sk_*`, issue #972 §2.3) resolves the same five facts into its own
+ * `req.machineCredential`, deliberately never `req.serviceApp` — populating the
+ * latter would hand a self-serve third-party credential the lane that only
+ * platform-trusted applications may enter. So a machine-credential request has
+ * no billing principal HERE and resolves `null`, which fails closed: the caller
+ * must handle it, and `getRequiredOxyBillingPrincipal` throws rather than
+ * charging anyone. One accessor answering for both lanes belongs to the public
+ * inference edge that has to admit both, and it needs the machine principal's
+ * shape to move into this package first.
+ */
+export function getOxyBillingPrincipal(req: Request): OxyBillingPrincipal | null {
+  const serviceApp = (req as OxyAuthRequest).serviceApp;
+  if (!serviceApp) {
+    return null;
+  }
+  const accountId = normalizeId(serviceApp.ownerAccountId);
+  const applicationId = normalizeId(serviceApp.appId);
+  const credentialId = normalizeId(serviceApp.credentialId);
+  if (!accountId || !applicationId || !credentialId) {
+    return null;
+  }
+  return {
+    accountId,
+    applicationId,
+    credentialId,
+    environment: serviceApp.environment,
+    scopes: serviceApp.scopes,
+  };
+}
+
+/**
+ * {@link getOxyBillingPrincipal}, throwing when the request has none. Use on
+ * routes that have already required a service token.
+ */
+export function getRequiredOxyBillingPrincipal(req: Request): OxyBillingPrincipal {
+  const principal = getOxyBillingPrincipal(req);
+  if (!principal) {
+    throw new Error('Request has no verified Oxy service principal');
+  }
+  return principal;
+}
+
+/**
+ * The delegated end user of a service request, or `null`.
+ *
+ * Deliberately reads `req.serviceActingAs` — the grant-verified delegation —
+ * and not `req.userId`, which on a non-service request is the caller's own
+ * session identity and is not a delegation at all.
+ */
+export function getOxyDelegatedUserId(req: Request): string | null {
+  return normalizeId((req as OxyAuthRequest).serviceActingAs?.userId);
+}
+
+/**
+ * The whole attribution tuple for a service request: who pays, which
+ * application and credential, and optionally on whose behalf.
+ */
+export function getOxyRequestAttribution(req: Request): OxyRequestAttribution | null {
+  const principal = getOxyBillingPrincipal(req);
+  if (!principal) {
+    return null;
+  }
+  return { ...principal, delegatedUserId: getOxyDelegatedUserId(req) };
+}
+
+export function getRequiredOxyUserId(req: Request): string {
+  const userId = getOxyUserId(req);
+  if (!userId) {
+    throw new Error('User not authenticated');
+  }
+  return userId;
+}
+
+export function requireOxyAuth(req: Request, res: Response, next: NextFunction): void {
+  const userId = getOxyUserId(req);
+  if (!userId) {
+    res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Authentication required',
+    });
+    return;
+  }
+
+  const authReq = req as OxyAuthRequest;
+  authReq.userId = userId;
+  ensureUser(authReq, userId);
+  next();
+}
+
+export function createOptionalOxyAuth(
+  oxy: OxyServices,
+  options: OxyAuthMiddlewareOptions = {},
+): RequestHandler {
+  const resolveSession = oxy.auth({ ...options.auth, optional: true });
+
+  return (req, res, next) => {
+    if (getOxyUserId(req)) {
+      next();
+      return;
+    }
+
+    resolveSession(req, res, (error?: unknown) => {
+      if (error) {
+        next(error);
+        return;
+      }
+      next();
+    });
+  };
+}
+
+export function createOxyAuthMiddleware(
+  oxy: OxyServices,
+  options: OxyAuthMiddlewareOptions = {},
+): RequestHandler {
+  const resolveSession = createOptionalOxyAuth(oxy, options);
+
+  return (req, res, next) => {
+    if (getOxyUserId(req)) {
+      requireOxyAuth(req, res, next);
+      return;
+    }
+
+    resolveSession(req, res, (error?: unknown) => {
+      if (error) {
+        next(error);
+        return;
+      }
+      requireOxyAuth(req, res, next);
+    });
+  };
+}

package/src/server/capabilityTicket.ts

@@ -0,0 +1,258 @@
+import {
+  randomUUID,
+  sign as signBytes,
+  verify as verifyBytes,
+  type KeyObject,
+} from 'node:crypto';
+import {
+  capabilityTicketClaimsSchema,
+  type CapabilityTicketClaims,
+  type GrantLimit,
+  type PolicyDecision,
+} from '@oxy.so/contracts';
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+
+const ALGORITHM = 'EdDSA';
+const TOKEN_TYPE = 'OXY-CAPABILITY+JWT';
+const DEFAULT_MAX_TTL_SECONDS = 300;
+
+type UnsignedCapabilityTicketClaims = Omit<CapabilityTicketClaims, 'iss' | 'iat' | 'exp' | 'jti'>;
+
+export interface CapabilityTicketSigningOptions {
+  privateKey: KeyObject;
+  keyId: string;
+  issuer: string;
+  ttlSeconds?: number;
+  now?: Date;
+  jti?: string;
+}
+
+export interface CapabilityTicketVerificationOptions {
+  resolvePublicKey: (keyId: string) => KeyObject | undefined;
+  audience: string;
+  issuer?: string;
+  now?: Date;
+  maximumTtlSeconds?: number;
+}
+
+export interface CapabilityTicketRequest extends Request {
+  capabilityTicket?: CapabilityTicketClaims;
+}
+
+export interface CapabilityTicketMiddlewareOptions extends CapabilityTicketVerificationOptions {
+  authorize: (claims: CapabilityTicketClaims) => Promise<PolicyDecision>;
+}
+
+export class CapabilityTicketError extends Error {
+  constructor(
+    public readonly code:
+      | 'malformed'
+      | 'invalid_signature'
+      | 'unknown_key'
+      | 'invalid_claims'
+      | 'expired'
+      | 'not_yet_valid'
+      | 'wrong_audience'
+      | 'wrong_issuer'
+      | 'ttl_exceeded',
+    message: string,
+  ) {
+    super(message);
+    this.name = 'CapabilityTicketError';
+  }
+}
+
+function base64UrlEncode(value: string | Uint8Array): string {
+  return Buffer.from(value).toString('base64url');
+}
+
+function decodeJsonSegment(segment: string): unknown {
+  try {
+    return JSON.parse(Buffer.from(segment, 'base64url').toString('utf8')) as unknown;
+  } catch {
+    throw new CapabilityTicketError('malformed', 'Capability ticket is not valid base64url JSON');
+  }
+}
+
+function valuesAtPath(input: Record<string, unknown>, path: string): unknown[] {
+  let current: unknown[] = [input];
+  for (const segment of path.split('.')) {
+    const next: unknown[] = [];
+    for (const value of current) {
+      const records = Array.isArray(value) ? value : [value];
+      for (const record of records) {
+        if (typeof record !== 'object' || record === null || Array.isArray(record)) continue;
+        if (Object.prototype.hasOwnProperty.call(record, segment)) {
+          next.push((record as Record<string, unknown>)[segment]);
+        }
+      }
+    }
+    if (next.length === 0) return [];
+    current = next;
+  }
+  return current.flatMap((value) => Array.isArray(value) ? value : [value]);
+}
+
+/** Enforces the signed per-action bounds before a domain handler runs. */
+export function inputSatisfiesCapabilityLimits(
+  tool: string,
+  input: Record<string, unknown>,
+  limits: readonly GrantLimit[],
+): boolean {
+  for (const limit of limits) {
+    if (limit.tool !== tool) return false;
+    const actualValues = valuesAtPath(input, limit.key);
+    if (actualValues.length === 0) return false;
+    if (typeof limit.value === 'number') {
+      const maximum = limit.value;
+      if (!actualValues.every((actual) => (
+        typeof actual === 'number' && Number.isFinite(actual) && actual <= maximum
+      ))) return false;
+      continue;
+    }
+    if (!actualValues.every((actual) => actual === limit.value)) return false;
+  }
+  return true;
+}
+
+export function issueCapabilityTicket(
+  claims: UnsignedCapabilityTicketClaims,
+  options: CapabilityTicketSigningOptions,
+): string {
+  const ttlSeconds = options.ttlSeconds ?? 60;
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > DEFAULT_MAX_TTL_SECONDS) {
+    throw new CapabilityTicketError('ttl_exceeded', `Capability ticket TTL must be between 1 and ${DEFAULT_MAX_TTL_SECONDS} seconds`);
+  }
+
+  const issuedAt = Math.floor((options.now ?? new Date()).getTime() / 1_000);
+  const payload = capabilityTicketClaimsSchema.parse({
+    ...claims,
+    iss: options.issuer,
+    iat: issuedAt,
+    exp: issuedAt + ttlSeconds,
+    jti: options.jti ?? randomUUID(),
+  });
+  if (options.privateKey.asymmetricKeyType !== 'ed25519') {
+    throw new CapabilityTicketError('invalid_claims', 'Capability tickets require an Ed25519 private key');
+  }
+  const header = { alg: ALGORITHM, typ: TOKEN_TYPE, kid: options.keyId } as const;
+  const signingInput = `${base64UrlEncode(JSON.stringify(header))}.${base64UrlEncode(JSON.stringify(payload))}`;
+  return `${signingInput}.${base64UrlEncode(signBytes(null, Buffer.from(signingInput), options.privateKey))}`;
+}
+
+export function verifyCapabilityTicket(
+  token: string,
+  options: CapabilityTicketVerificationOptions,
+): CapabilityTicketClaims {
+  const segments = token.split('.');
+  if (segments.length !== 3) {
+    throw new CapabilityTicketError('malformed', 'Capability ticket must have three segments');
+  }
+  const [encodedHeader, encodedPayload, encodedSignature] = segments;
+  if (!encodedHeader || !encodedPayload || !encodedSignature) {
+    throw new CapabilityTicketError('malformed', 'Capability ticket contains an empty segment');
+  }
+
+  const header = decodeJsonSegment(encodedHeader);
+  if (typeof header !== 'object' || header === null || Array.isArray(header)) {
+    throw new CapabilityTicketError('malformed', 'Capability ticket header is not supported');
+  }
+  const headerRecord = header as Record<string, unknown>;
+  if (
+    Object.keys(headerRecord).length !== 3
+    || headerRecord.alg !== ALGORITHM
+    || headerRecord.typ !== TOKEN_TYPE
+    || typeof headerRecord.kid !== 'string'
+    || headerRecord.kid.length === 0
+  ) {
+    throw new CapabilityTicketError('malformed', 'Capability ticket header is not supported');
+  }
+  const publicKey = options.resolvePublicKey(headerRecord.kid);
+  if (!publicKey || publicKey.asymmetricKeyType !== 'ed25519') {
+    throw new CapabilityTicketError('unknown_key', 'Capability ticket signing key is not trusted');
+  }
+  let providedSignature: Buffer;
+  try {
+    providedSignature = Buffer.from(encodedSignature, 'base64url');
+  } catch {
+    throw new CapabilityTicketError('malformed', 'Capability ticket signature is malformed');
+  }
+  if (!verifyBytes(
+    null,
+    Buffer.from(`${encodedHeader}.${encodedPayload}`),
+    publicKey,
+    providedSignature,
+  )) {
+    throw new CapabilityTicketError('invalid_signature', 'Capability ticket signature is invalid');
+  }
+
+  const parsed = capabilityTicketClaimsSchema.safeParse(decodeJsonSegment(encodedPayload));
+  if (!parsed.success) {
+    throw new CapabilityTicketError('invalid_claims', 'Capability ticket claims are invalid');
+  }
+
+  const claims = parsed.data;
+  const now = Math.floor((options.now ?? new Date()).getTime() / 1_000);
+  if (claims.iat > now + 5) {
+    throw new CapabilityTicketError('not_yet_valid', 'Capability ticket is not yet valid');
+  }
+  if (claims.exp <= now) {
+    throw new CapabilityTicketError('expired', 'Capability ticket has expired');
+  }
+  if (claims.exp - claims.iat > (options.maximumTtlSeconds ?? DEFAULT_MAX_TTL_SECONDS)) {
+    throw new CapabilityTicketError('ttl_exceeded', 'Capability ticket lifetime exceeds the accepted maximum');
+  }
+  if (claims.aud !== options.audience) {
+    throw new CapabilityTicketError('wrong_audience', 'Capability ticket audience does not match this app');
+  }
+  if (options.issuer && claims.iss !== options.issuer) {
+    throw new CapabilityTicketError('wrong_issuer', 'Capability ticket issuer is not trusted');
+  }
+
+  return claims;
+}
+
+export function readCapabilityAuthorization(authorization: string | undefined): string | null {
+  if (!authorization) return null;
+  const [scheme, token, extra] = authorization.trim().split(/\s+/);
+  if (scheme?.toLowerCase() !== 'capability' || !token || extra) return null;
+  return token;
+}
+
+/**
+ * Verifies cryptographic scope first, then asks the authority service for a
+ * live decision. This second check is what makes revocation effective between
+ * planning and execution.
+ */
+export function createCapabilityTicketMiddleware(
+  options: CapabilityTicketMiddlewareOptions,
+): RequestHandler {
+  return async (request: Request, response: Response, next: NextFunction): Promise<void> => {
+    const token = readCapabilityAuthorization(request.header('authorization'));
+    if (!token) {
+      response.status(401).json({ error: 'capability_ticket_required' });
+      return;
+    }
+
+    let claims: CapabilityTicketClaims;
+    try {
+      claims = verifyCapabilityTicket(token, options);
+    } catch (error) {
+      const code = error instanceof CapabilityTicketError ? error.code : 'invalid_claims';
+      response.status(401).json({ error: 'invalid_capability_ticket', code });
+      return;
+    }
+
+    try {
+      const decision = await options.authorize(claims);
+      if (!decision.allowed) {
+        response.status(403).json({ error: 'capability_denied', reason: decision.reason });
+        return;
+      }
+      (request as CapabilityTicketRequest).capabilityTicket = claims;
+      next();
+    } catch {
+      response.status(503).json({ error: 'capability_authority_unavailable' });
+    }
+  };
+}