Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

5.8 KB
Raw Blame
import {
  ALL_SCOPE_STRINGS,
  isValidScopePair,
  OIDC_STANDARD_SCOPES,
  SCOPE_MATRIX,
  SCOPE_RESOURCES,
  type ScopeAction,
  type ScopeRequirement,
  type ScopeResource,
  type ScopeStatements,
} from "@rybbit/shared";
import { role } from "better-auth/plugins/access";
import { z } from "zod";

/**
 * Enforcement helpers for the scope taxonomy defined in @rybbit/shared.
 *
 * The same resource:action pairs serve both credential types: API keys store
 * them as a Record<resource, actions[]> in better-auth's `permissions` field,
 * OAuth tokens carry them as space-separated "resource:action" scope strings.
 *
 * Semantics:
 * - `null` statements = UNRESTRICTED (legacy credentials created before scopes
 *   existed, or credentials deliberately issued with full access).
 * - `{}` statements = deny-all. Never conflate the two.
 * - `write` implies `read` on the same resource (a goals:write credential can
 *   list goals). Checked in hasScope, not stored.
 * - Scopes only constrain bearer credentials; cookie sessions bypass them.
 * - Scopes never elevate: role requirements (org admin/owner) still apply.
 *
 * Leaf module: keep free of ./auth.js imports so the MCP tools and their tests
 * can load it without dragging in the better-auth init chain.
 */
// Re-export the shared taxonomy so existing server imports keep resolving here.
export { ALL_SCOPE_STRINGS, OIDC_STANDARD_SCOPES, SCOPE_MATRIX };
export type { ScopeAction, ScopeRequirement, ScopeResource, ScopeStatements };

const isValidPair = isValidScopePair;

export function scopeToString(requirement: ScopeRequirement): string {
  return `${requirement.resource}:${requirement.action}`;
}

export function toScopeStrings(statements: ScopeStatements): string[] {
  return Object.entries(statements).flatMap(([resource, actions]) =>
    (actions ?? []).map(action => `${resource}:${action}`)
  );
}

/**
 * OAuth scope string (space-separated) β†’ statements.
 * Standard OIDC scopes are stripped first; if nothing custom remains the
 * credential predates scoping (or requested none) and is UNRESTRICTED (null).
 * When custom entries are present, unknown ones are dropped but the result
 * stays non-null β€” a token carrying only unknown custom scopes gets {} and is
 * denied everything (fail closed).
 */
export function parseOAuthScopes(scope: string | null | undefined): ScopeStatements | null {
  const custom = (scope ?? "")
    .split(/\s+/)
    .filter(Boolean)
    .filter(entry => !(OIDC_STANDARD_SCOPES as readonly string[]).includes(entry));

  if (custom.length === 0) {
    return null;
  }

  const statements: ScopeStatements = {};
  for (const entry of custom) {
    const [resource, action, ...rest] = entry.split(":");
    if (!resource || !action || rest.length > 0 || !isValidPair(resource, action)) {
      continue;
    }
    const existing = statements[resource] ?? [];
    if (!existing.includes(action as ScopeAction)) {
      statements[resource] = [...existing, action as ScopeAction];
    }
  }
  return statements;
}

/**
 * API-key permissions (the PARSED object from verifyApiKey's result.key) β†’
 * statements. null/undefined = legacy key = UNRESTRICTED. Anything else keeps
 * only valid resource/action entries; malformed input yields {} (fail closed).
 */
export function statementsFromApiKeyPermissions(permissions: unknown): ScopeStatements | null {
  if (permissions === null || permissions === undefined) {
    return null;
  }

  const statements: ScopeStatements = {};
  if (typeof permissions === "object" && !Array.isArray(permissions)) {
    for (const [resource, actions] of Object.entries(permissions)) {
      if (!Array.isArray(actions)) continue;
      const valid = actions.filter(
        (action): action is ScopeAction => typeof action === "string" && isValidPair(resource, action)
      );
      if (valid.length > 0) {
        statements[resource as ScopeResource] = [...new Set(valid)];
      }
    }
  }
  return statements;
}

/**
 * Does the credential satisfy the requirement? null = unrestricted. A `read`
 * requirement is satisfied by `write` on the same resource. Delegates the
 * subset match to better-auth's access matcher.
 */
export function hasScope(statements: ScopeStatements | null, requirement: ScopeRequirement): boolean {
  if (statements === null) {
    return true;
  }
  const matcher = role(statements as Record<string, string[]>);
  if (matcher.authorize({ [requirement.resource]: [requirement.action] }).success) {
    return true;
  }
  if (requirement.action === "read") {
    return matcher.authorize({ [requirement.resource]: ["write"] }).success;
  }
  return false;
}

/**
 * Body schema for scoped API-key creation. Omit `permissions` entirely for a
 * full-access key; an empty object would create a key that can do nothing, so
 * it is rejected.
 */
export const apiKeyPermissionsSchema = z
  .record(z.string(), z.array(z.string()).min(1, "Each resource needs at least one action"))
  .superRefine((value, ctx) => {
    const entries = Object.entries(value);
    if (entries.length === 0) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: "Omit permissions entirely for full access; an empty permissions object would deny everything",
      });
      return;
    }
    for (const [resource, actions] of entries) {
      if (!SCOPE_RESOURCES.includes(resource as ScopeResource)) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          message: `Unknown resource "${resource}". Valid resources: ${SCOPE_RESOURCES.join(", ")}`,
        });
        continue;
      }
      for (const action of actions) {
        if (!isValidPair(resource, action)) {
          ctx.addIssue({
            code: z.ZodIssueCode.custom,
            message: `Invalid action "${action}" for resource "${resource}". Valid: ${(SCOPE_MATRIX[resource as ScopeResource] as readonly string[]).join(", ")}`,
          });
        }
      }
    }
  }) as z.ZodType<ScopeStatements>;