@hilbras/keystone 2.5.0 → 2.6.0

package/dist/services/scopes.js

@@ -0,0 +1,138 @@
+/**
+ * API key scope registry.
+ *
+ * API key scopes used to be decorative. `requireScopes` existed and was
+ * decorated onto the Fastify instance, but no route referenced it, so a key
+ * issued with the default `["api:read"]` carried exactly the same authority as
+ * the user who created it. Scopes were also free-form: a caller could request
+ * any string at key creation, including the literal `"service_account"` that
+ * `requireScopes` treated as a wildcard.
+ *
+ * A registry fixes both halves. A scope that is not defined here cannot be
+ * granted, so there is no string an attacker can invent; and a route that needs a
+ * scope names it from this list, so enforcement cannot silently drift out of
+ * date the way an unreferenced decorator did.
+ */
+/** Every scope Keystone recognises. Order is the order shown to operators. */
+export const API_KEY_SCOPES = {
+    /** Read the caller's own profile, sessions, and keys. */
+    "profile:read": "Read your own profile and identity",
+    "profile:write": "Update your own profile",
+    /** Read sessions belonging to the caller. */
+    "sessions:read": "List your own sessions",
+    "sessions:revoke": "Revoke your own sessions",
+    /** Manage the caller's own API keys. */
+    "api_keys:read": "List your own API keys",
+    "api_keys:revoke": "Revoke your own API keys",
+    /** Read organization members and applications. */
+    "organizations:read": "Read organization membership and applications",
+    /** Manage organization members, applications, and roles. */
+    "organizations:write": "Manage organization membership and applications",
+    /** Read and manage webhooks. */
+    "webhooks:manage": "Create, update, and delete webhooks",
+    /** Read and manage workflows. */
+    "workflows:read": "Read workflows and their runs",
+    "workflows:write": "Create and update workflows",
+    /** Second-factor management. Never appropriate for a machine credential. */
+    "mfa:manage": "Enroll, verify, and disable TOTP and backup codes",
+};
+const ALL_SCOPES = Object.keys(API_KEY_SCOPES);
+export function isApiKeyScope(value) {
+    return Object.prototype.hasOwnProperty.call(API_KEY_SCOPES, value);
+}
+export function knownScopes() {
+    return [...ALL_SCOPES];
+}
+/** Human-readable description of a scope, for API responses and dashboards. */
+export function describeScope(scope) {
+    return isApiKeyScope(scope) ? API_KEY_SCOPES[scope] : undefined;
+}
+/**
+ * Scopes granted to a service account by default.
+ *
+ * Deliberately excludes anything interactive: a machine credential has no user
+ * present to complete a second factor, no real profile, and no sessions worth
+ * listing. A service account that needs more is granted it explicitly.
+ */
+export const SERVICE_ACCOUNT_DEFAULT_SCOPES = ["organizations:read"];
+/**
+ * Scopes a new personal API key receives when the caller names none.
+ *
+ * Read-only and confined to the caller's own resources. The previous default,
+ * `["api:read"]`, was not in the registry at all — which is a fair indicator that
+ * nothing was checking it.
+ */
+export const PERSONAL_KEY_DEFAULT_SCOPES = ["profile:read", "sessions:read", "api_keys:read"];
+/**
+ * Scopes that may never be granted to a machine credential.
+ *
+ * `mfa:manage` because a second factor is enrolled by a person holding an
+ * authenticator; `MfaRequiredError` is raised when a token is minted for a user
+ * with TOTP enabled and no recorded factor, and a service account has no
+ * authenticator to record.
+ *
+ * `profile:*` because a service account's "profile" is a synthesized object with
+ * an id of `sa:<uuid>` that matches no user row. Reading it returns nothing real,
+ * and writing it would update zero rows -- so the scope is meaningless for a
+ * machine and misleading in an audit log that shows what a key was used for.
+ */
+export const HUMAN_ONLY_SCOPES = [
+    "mfa:manage",
+    "profile:read",
+    "profile:write",
+];
+/**
+ * Validate a requested scope set.
+ *
+ * Unknown scopes are refused rather than dropped. Silently discarding a scope a
+ * caller asked for hides both a typo and an attempt to smuggle an unrecognised
+ * privilege past a review, and it leaves the caller believing they hold
+ * something they do not.
+ */
+export function validateScopes(requested, options = { principal: "user" }) {
+    const wanted = requested && requested.length > 0
+        ? requested
+        : (options.fallback ??
+            (options.principal === "service_account" ? SERVICE_ACCOUNT_DEFAULT_SCOPES : PERSONAL_KEY_DEFAULT_SCOPES));
+    const unknown = wanted.filter((scope) => !isApiKeyScope(scope));
+    const known = wanted.filter(isApiKeyScope);
+    const forbidden = options.principal === "service_account"
+        ? known.filter((scope) => HUMAN_ONLY_SCOPES.includes(scope))
+        : [];
+    const allowed = known.filter((scope) => !forbidden.includes(scope));
+    return {
+        ok: unknown.length === 0 && forbidden.length === 0,
+        unknown,
+        forbiddenForServiceAccount: forbidden,
+        // Registry order, so two equivalent requests produce identical rows.
+        scopes: ALL_SCOPES.filter((scope) => allowed.includes(scope)),
+    };
+}
+/**
+ * Narrow a key's stored scopes to what the caller is actually entitled to.
+ *
+ * A key never gains authority from its own record. The effective set is what the
+ * key holds *intersected with* what its principal could do directly, so revoking
+ * a role or removing a membership takes effect on the key too rather than
+ * leaving a stale grant behind.
+ */
+export function intersectScopes(granted, principalAllows) {
+    const held = new Set((granted ?? []).filter(isApiKeyScope));
+    const allowed = new Set(principalAllows.filter(isApiKeyScope));
+    return ALL_SCOPES.filter((scope) => held.has(scope) && allowed.has(scope));
+}
+/**
+ * Grant check used by `requireScopes`.
+ *
+ * Explicit allow-list membership only. The previous implementation also accepted
+ * a key whose scopes merely *contained* the string `"service_account"`, which is
+ * a bypass by construction: that string was client-suppliable at key creation, so
+ * any key created with `scopes: ["service_account"]` satisfied every check.
+ */
+export function hasScopes(granted, required) {
+    if (required.length === 0)
+        return true;
+    const held = new Set(granted ?? []);
+    return required.every((scope) => held.has(scope));
+}
+//# sourceMappingURL=scopes.js.map

package/dist/services/scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../../src/services/scopes.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hilbras/keystone",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "license": "MIT",
   "description": "Hilbras Keystone — standalone identity platform: authentication, MFA, authorization, enterprise SSO, SCIM, and token issuance.",
   "repository": {