@connectum/auth 1.0.0-rc.3

package/dist/index.js

@@ -0,0 +1,637 @@
+// src/auth-interceptor.ts
+import { Code as Code2, ConnectError as ConnectError2 } from "@connectrpc/connect";
+
+// src/cache.ts
+var LruCache = class {
+  #maxSize;
+  #ttl;
+  #entries = /* @__PURE__ */ new Map();
+  constructor(options) {
+    if (typeof options.ttl !== "number" || options.ttl <= 0) {
+      throw new RangeError("ttl must be a positive number");
+    }
+    this.#ttl = options.ttl;
+    this.#maxSize = options.maxSize ?? 1e3;
+  }
+  get(key) {
+    const entry = this.#entries.get(key);
+    if (!entry) return void 0;
+    if (Date.now() >= entry.expiresAt) {
+      this.#entries.delete(key);
+      return void 0;
+    }
+    this.#entries.delete(key);
+    this.#entries.set(key, entry);
+    return entry.value;
+  }
+  set(key, value) {
+    this.#entries.delete(key);
+    if (this.#entries.size >= this.#maxSize) {
+      const firstKey = this.#entries.keys().next().value;
+      if (firstKey !== void 0) {
+        this.#entries.delete(firstKey);
+      }
+    }
+    this.#entries.set(key, {
+      value,
+      expiresAt: Date.now() + this.#ttl
+    });
+  }
+  clear() {
+    this.#entries.clear();
+  }
+  get size() {
+    return this.#entries.size;
+  }
+};
+
+// src/context.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { Code, ConnectError } from "@connectrpc/connect";
+var authContextStorage = new AsyncLocalStorage();
+function getAuthContext() {
+  return authContextStorage.getStore();
+}
+function requireAuthContext() {
+  const context = authContextStorage.getStore();
+  if (!context) {
+    throw new ConnectError("Authentication required", Code.Unauthenticated);
+  }
+  return context;
+}
+
+// src/types.ts
+var AUTH_HEADERS = {
+  /** Authenticated subject identifier */
+  SUBJECT: "x-auth-subject",
+  /** JSON-encoded roles array */
+  ROLES: "x-auth-roles",
+  /** Space-separated scopes */
+  SCOPES: "x-auth-scopes",
+  /** JSON-encoded claims object */
+  CLAIMS: "x-auth-claims",
+  /** Human-readable display name */
+  NAME: "x-auth-name",
+  /** Credential type (jwt, api-key, mtls, etc.) */
+  TYPE: "x-auth-type"
+};
+var AuthzEffect = {
+  ALLOW: "allow",
+  DENY: "deny"
+};
+
+// src/headers.ts
+var MAX_HEADER_BYTES = 8192;
+function sanitizeHeaderValue(value, maxLength) {
+  const cleaned = value.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+  return cleaned.slice(0, maxLength);
+}
+function setAuthHeaders(headers, context, propagatedClaims) {
+  headers.set(AUTH_HEADERS.SUBJECT, sanitizeHeaderValue(context.subject, 512));
+  headers.set(AUTH_HEADERS.TYPE, sanitizeHeaderValue(context.type, 128));
+  if (context.name) {
+    headers.set(AUTH_HEADERS.NAME, sanitizeHeaderValue(context.name, 256));
+  }
+  if (context.roles.length > 0) {
+    const rolesValue = JSON.stringify(context.roles);
+    if (rolesValue.length <= MAX_HEADER_BYTES) {
+      headers.set(AUTH_HEADERS.ROLES, rolesValue);
+    }
+  }
+  if (context.scopes.length > 0) {
+    const scopesValue = context.scopes.join(" ");
+    if (scopesValue.length <= MAX_HEADER_BYTES) {
+      headers.set(AUTH_HEADERS.SCOPES, scopesValue);
+    }
+  }
+  const claimKeys = Object.keys(context.claims);
+  if (claimKeys.length > 0) {
+    const filteredClaims = propagatedClaims ? Object.fromEntries(Object.entries(context.claims).filter(([key]) => propagatedClaims.includes(key))) : context.claims;
+    if (Object.keys(filteredClaims).length > 0) {
+      const claimsValue = JSON.stringify(filteredClaims);
+      if (claimsValue.length <= MAX_HEADER_BYTES) {
+        headers.set(AUTH_HEADERS.CLAIMS, claimsValue);
+      }
+    }
+  }
+}
+function parseAuthHeaders(headers) {
+  const subjectHeader = headers.get(AUTH_HEADERS.SUBJECT);
+  if (!subjectHeader) {
+    return void 0;
+  }
+  const subject = sanitizeHeaderValue(subjectHeader, 512);
+  const typeHeader = headers.get(AUTH_HEADERS.TYPE);
+  const type = typeHeader ? sanitizeHeaderValue(typeHeader, 128) : "unknown";
+  const rolesRaw = headers.get(AUTH_HEADERS.ROLES);
+  const scopesRaw = headers.get(AUTH_HEADERS.SCOPES);
+  const claimsRaw = headers.get(AUTH_HEADERS.CLAIMS);
+  let roles = [];
+  if (rolesRaw && rolesRaw.length <= MAX_HEADER_BYTES) {
+    try {
+      const parsed = JSON.parse(rolesRaw);
+      if (Array.isArray(parsed)) {
+        roles = parsed.filter((r) => typeof r === "string");
+      }
+    } catch {
+    }
+  }
+  let scopes = [];
+  if (scopesRaw && scopesRaw.length <= MAX_HEADER_BYTES) {
+    scopes = scopesRaw.split(" ").filter(Boolean);
+  }
+  const nameRaw = headers.get(AUTH_HEADERS.NAME);
+  const name = nameRaw ? sanitizeHeaderValue(nameRaw, 256) : void 0;
+  let claims = {};
+  if (claimsRaw) {
+    if (claimsRaw.length > MAX_HEADER_BYTES) {
+      claims = {};
+    } else {
+      try {
+        const parsed = JSON.parse(claimsRaw);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+          claims = parsed;
+        }
+      } catch {
+      }
+    }
+  }
+  return {
+    subject,
+    name,
+    type,
+    roles,
+    scopes,
+    claims
+  };
+}
+
+// src/method-match.ts
+function matchesMethodPattern(serviceName, methodName, patterns) {
+  if (patterns.length === 0) {
+    return false;
+  }
+  const fullMethod = `${serviceName}/${methodName}`;
+  for (const pattern of patterns) {
+    if (pattern === "*") {
+      return true;
+    }
+    if (pattern === fullMethod) {
+      return true;
+    }
+    if (pattern.endsWith("/*")) {
+      const servicePattern = pattern.slice(0, -2);
+      if (serviceName === servicePattern) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// src/auth-interceptor.ts
+function defaultExtractCredentials(req) {
+  const authHeader = req.header.get("authorization");
+  if (!authHeader) {
+    return null;
+  }
+  const match = /^Bearer\s+(.+)$/i.exec(authHeader);
+  return match?.[1] ?? null;
+}
+function createAuthInterceptor(options) {
+  const { extractCredentials = defaultExtractCredentials, verifyCredentials, skipMethods = [], propagateHeaders = false, cache: cacheOptions, propagatedClaims } = options;
+  const cache = cacheOptions ? new LruCache(cacheOptions) : void 0;
+  return (next) => async (req) => {
+    const serviceName = req.service.typeName;
+    const methodName = req.method.name;
+    for (const headerName of Object.values(AUTH_HEADERS)) {
+      req.header.delete(headerName);
+    }
+    if (matchesMethodPattern(serviceName, methodName, skipMethods)) {
+      return await next(req);
+    }
+    const credentials = await extractCredentials(req);
+    if (!credentials) {
+      throw new ConnectError2("Missing credentials", Code2.Unauthenticated);
+    }
+    const cached = cache?.get(credentials);
+    if (cached && (!cached.expiresAt || cached.expiresAt.getTime() > Date.now())) {
+      if (propagateHeaders) {
+        setAuthHeaders(req.header, cached, propagatedClaims);
+      }
+      return await authContextStorage.run(cached, () => next(req));
+    }
+    let authContext;
+    try {
+      authContext = await verifyCredentials(credentials);
+    } catch (err) {
+      if (err instanceof ConnectError2) {
+        throw err;
+      }
+      throw new ConnectError2("Authentication failed", Code2.Unauthenticated);
+    }
+    cache?.set(credentials, authContext);
+    if (propagateHeaders) {
+      setAuthHeaders(req.header, authContext, propagatedClaims);
+    }
+    return await authContextStorage.run(authContext, () => next(req));
+  };
+}
+
+// src/authz-interceptor.ts
+import { Code as Code4, ConnectError as ConnectError4 } from "@connectrpc/connect";
+
+// src/errors.ts
+import { Code as Code3, ConnectError as ConnectError3 } from "@connectrpc/connect";
+var AuthzDeniedError = class extends ConnectError3 {
+  clientMessage = "Access denied";
+  ruleName;
+  authzDetails;
+  get serverDetails() {
+    return {
+      ruleName: this.authzDetails.ruleName,
+      requiredRoles: this.authzDetails.requiredRoles,
+      requiredScopes: this.authzDetails.requiredScopes
+    };
+  }
+  constructor(details) {
+    super(`Access denied by rule: ${details.ruleName}`, Code3.PermissionDenied);
+    this.name = "AuthzDeniedError";
+    this.ruleName = details.ruleName;
+    this.authzDetails = details;
+  }
+};
+
+// src/authz-interceptor.ts
+function satisfiesRequirements(context, requires) {
+  if (requires.roles && requires.roles.length > 0) {
+    const hasRole = requires.roles.some((role) => context.roles.includes(role));
+    if (!hasRole) {
+      return false;
+    }
+  }
+  if (requires.scopes && requires.scopes.length > 0) {
+    const hasAllScopes = requires.scopes.every((scope) => context.scopes.includes(scope));
+    if (!hasAllScopes) {
+      return false;
+    }
+  }
+  return true;
+}
+function evaluateRules(rules, context, serviceName, methodName) {
+  for (const rule of rules) {
+    const matches = matchesMethodPattern(serviceName, methodName, rule.methods);
+    if (!matches) {
+      continue;
+    }
+    if (rule.requires) {
+      if (satisfiesRequirements(context, rule.requires)) {
+        const result = {
+          effect: rule.effect,
+          ruleName: rule.name
+        };
+        if (rule.requires.roles) result.requiredRoles = rule.requires.roles;
+        if (rule.requires.scopes) result.requiredScopes = rule.requires.scopes;
+        return result;
+      }
+      continue;
+    }
+    return { effect: rule.effect, ruleName: rule.name };
+  }
+  return void 0;
+}
+function createAuthzInterceptor(options = {}) {
+  const { defaultPolicy = AuthzEffect.DENY, rules = [], authorize, skipMethods = [] } = options;
+  return (next) => async (req) => {
+    const serviceName = req.service.typeName;
+    const methodName = req.method.name;
+    if (matchesMethodPattern(serviceName, methodName, skipMethods)) {
+      return await next(req);
+    }
+    const authContext = getAuthContext();
+    if (!authContext) {
+      throw new ConnectError4("Authentication required for authorization", Code4.Unauthenticated);
+    }
+    if (rules.length > 0) {
+      const ruleResult = evaluateRules(rules, authContext, serviceName, methodName);
+      if (ruleResult) {
+        if (ruleResult.effect === AuthzEffect.DENY) {
+          const details = {
+            ruleName: ruleResult.ruleName,
+            ...ruleResult.requiredRoles && { requiredRoles: [...ruleResult.requiredRoles] },
+            ...ruleResult.requiredScopes && { requiredScopes: [...ruleResult.requiredScopes] }
+          };
+          throw new AuthzDeniedError(details);
+        }
+        return await next(req);
+      }
+    }
+    if (authorize) {
+      const allowed = await authorize(authContext, { service: serviceName, method: methodName });
+      if (!allowed) {
+        throw new ConnectError4("Access denied", Code4.PermissionDenied);
+      }
+      return await next(req);
+    }
+    if (defaultPolicy === AuthzEffect.DENY) {
+      throw new ConnectError4("Access denied by default policy", Code4.PermissionDenied);
+    }
+    return await next(req);
+  };
+}
+
+// src/gateway-auth-interceptor.ts
+import { Code as Code5, ConnectError as ConnectError5 } from "@connectrpc/connect";
+function isValidOctet(value) {
+  return Number.isInteger(value) && value >= 0 && value <= 255;
+}
+function matchesIp(address, pattern) {
+  if (address === pattern) return true;
+  if (pattern.includes("/")) {
+    const [network, prefixStr] = pattern.split("/");
+    if (!network || !prefixStr) return false;
+    const prefix = Number.parseInt(prefixStr, 10);
+    if (Number.isNaN(prefix) || prefix < 0 || prefix > 32) return false;
+    const peerParts = address.split(".").map(Number);
+    const networkParts = network.split(".").map(Number);
+    if (peerParts.length !== 4 || networkParts.length !== 4) return false;
+    if (!peerParts.every(isValidOctet) || !networkParts.every(isValidOctet)) return false;
+    const [p0 = 0, p1 = 0, p2 = 0, p3 = 0] = peerParts;
+    const [n0 = 0, n1 = 0, n2 = 0, n3 = 0] = networkParts;
+    const peerInt = (p0 << 24 | p1 << 16 | p2 << 8 | p3) >>> 0;
+    const networkInt = (n0 << 24 | n1 << 16 | n2 << 8 | n3) >>> 0;
+    const mask = prefix === 0 ? 0 : ~0 << 32 - prefix >>> 0;
+    return (peerInt & mask) === (networkInt & mask);
+  }
+  return false;
+}
+function isTrusted(headerValue, expectedValues) {
+  for (const expected of expectedValues) {
+    if (headerValue === expected) return true;
+    if (expected.includes("/") && matchesIp(headerValue, expected)) return true;
+  }
+  return false;
+}
+function createGatewayAuthInterceptor(options) {
+  const { headerMapping, trustSource, stripHeaders = [], skipMethods = [], propagateHeaders = false, defaultType = "gateway" } = options;
+  if (!headerMapping.subject) {
+    throw new Error("@connectum/auth: Gateway auth requires headerMapping.subject");
+  }
+  if (trustSource.expectedValues.length === 0) {
+    throw new Error("@connectum/auth: Gateway auth requires non-empty trustSource.expectedValues");
+  }
+  const headersToStrip = [
+    headerMapping.subject,
+    headerMapping.name,
+    headerMapping.roles,
+    headerMapping.scopes,
+    headerMapping.type,
+    headerMapping.claims,
+    trustSource.header,
+    ...stripHeaders
+  ];
+  function stripGatewayHeaders(headers) {
+    for (const header of headersToStrip) {
+      if (header) headers.delete(header);
+    }
+  }
+  return (next) => async (req) => {
+    const serviceName = req.service.typeName;
+    const methodName = req.method.name;
+    if (matchesMethodPattern(serviceName, methodName, skipMethods)) {
+      stripGatewayHeaders(req.header);
+      return await next(req);
+    }
+    const trustHeaderValue = req.header.get(trustSource.header);
+    if (!trustHeaderValue || !isTrusted(trustHeaderValue, trustSource.expectedValues)) {
+      throw new ConnectError5("Untrusted request source", Code5.Unauthenticated);
+    }
+    const subject = req.header.get(headerMapping.subject);
+    if (!subject) {
+      throw new ConnectError5("Missing subject header from gateway", Code5.Unauthenticated);
+    }
+    const name = headerMapping.name ? req.header.get(headerMapping.name) ?? void 0 : void 0;
+    const type = headerMapping.type ? req.header.get(headerMapping.type) ?? defaultType : defaultType;
+    let roles = [];
+    if (headerMapping.roles) {
+      const rolesRaw = req.header.get(headerMapping.roles);
+      if (rolesRaw) {
+        try {
+          const parsed = JSON.parse(rolesRaw);
+          if (Array.isArray(parsed)) {
+            roles = parsed.filter((r) => typeof r === "string");
+          }
+        } catch {
+          roles = rolesRaw.split(",").map((r) => r.trim()).filter(Boolean);
+        }
+      }
+    }
+    let scopes = [];
+    if (headerMapping.scopes) {
+      const scopesRaw = req.header.get(headerMapping.scopes);
+      if (scopesRaw) {
+        scopes = scopesRaw.split(" ").filter(Boolean);
+      }
+    }
+    let claims = {};
+    if (headerMapping.claims) {
+      const claimsRaw = req.header.get(headerMapping.claims);
+      if (claimsRaw && claimsRaw.length <= 8192) {
+        try {
+          const parsed = JSON.parse(claimsRaw);
+          if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            claims = parsed;
+          }
+        } catch {
+        }
+      }
+    }
+    const authContext = { subject, name, roles, scopes, claims, type };
+    stripGatewayHeaders(req.header);
+    if (propagateHeaders) {
+      setAuthHeaders(req.header, authContext);
+    }
+    return await authContextStorage.run(authContext, () => next(req));
+  };
+}
+
+// src/jwt-auth-interceptor.ts
+import { Code as Code6, ConnectError as ConnectError6 } from "@connectrpc/connect";
+import * as jose from "jose";
+function getNestedValue(obj, path) {
+  let current = obj;
+  for (const key of path.split(".")) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[key];
+  }
+  return current;
+}
+function getMinHmacKeyBytes(algorithms) {
+  if (!algorithms) return 32;
+  if (algorithms.includes("HS512")) return 64;
+  if (algorithms.includes("HS384")) return 48;
+  return 32;
+}
+function buildVerifier(options, verifyOptions) {
+  if (options.jwksUri) {
+    const jwks = jose.createRemoteJWKSet(new URL(options.jwksUri));
+    return (token) => jose.jwtVerify(token, jwks, verifyOptions);
+  }
+  if (options.secret) {
+    const key = new TextEncoder().encode(options.secret);
+    const minBytes = getMinHmacKeyBytes(options.algorithms);
+    if (key.byteLength < minBytes) {
+      throw new Error(
+        `@connectum/auth: HMAC secret must be at least ${minBytes} bytes (${minBytes * 8} bits) per RFC 7518. Got ${key.byteLength} bytes. Generate with: openssl rand -base64 ${minBytes}`
+      );
+    }
+    return (token) => jose.jwtVerify(token, key, verifyOptions);
+  }
+  if (options.publicKey) {
+    const key = options.publicKey;
+    return (token) => jose.jwtVerify(token, key, verifyOptions);
+  }
+  throw new Error("@connectum/auth: JWT interceptor requires one of: jwksUri, secret, or publicKey");
+}
+function mapClaimsToContext(payload, mapping) {
+  const result = {};
+  const claims = payload;
+  if (mapping.subject) {
+    const val = getNestedValue(claims, mapping.subject);
+    if (typeof val === "string") {
+      result.subject = val;
+    }
+  }
+  if (mapping.name) {
+    const val = getNestedValue(claims, mapping.name);
+    if (typeof val === "string") {
+      result.name = val;
+    }
+  }
+  if (mapping.roles) {
+    const val = getNestedValue(claims, mapping.roles);
+    if (Array.isArray(val)) {
+      result.roles = val.filter((r) => typeof r === "string");
+    }
+  }
+  if (mapping.scopes) {
+    const val = getNestedValue(claims, mapping.scopes);
+    if (typeof val === "string") {
+      result.scopes = val.split(" ").filter(Boolean);
+    } else if (Array.isArray(val)) {
+      result.scopes = val.filter((s) => typeof s === "string");
+    }
+  }
+  return result;
+}
+function throwMissingSubject() {
+  throw new ConnectError6("JWT missing subject claim", Code6.Unauthenticated);
+}
+function createJwtAuthInterceptor(options) {
+  const { claimsMapping = {}, skipMethods, propagateHeaders } = options;
+  const verifyOptions = {};
+  if (options.issuer) {
+    verifyOptions.issuer = options.issuer;
+  }
+  if (options.audience) {
+    verifyOptions.audience = options.audience;
+  }
+  if (options.algorithms) {
+    verifyOptions.algorithms = options.algorithms;
+  }
+  if (options.maxTokenAge) {
+    verifyOptions.maxTokenAge = options.maxTokenAge;
+  }
+  const verify = buildVerifier(options, verifyOptions);
+  return createAuthInterceptor({
+    skipMethods,
+    propagateHeaders,
+    verifyCredentials: async (token) => {
+      const { payload } = await verify(token);
+      const mapped = mapClaimsToContext(payload, claimsMapping);
+      const claims = payload;
+      return {
+        subject: mapped.subject ?? payload.sub ?? throwMissingSubject(),
+        name: mapped.name ?? (typeof claims.name === "string" ? claims.name : void 0),
+        roles: mapped.roles ?? [],
+        scopes: mapped.scopes ?? (typeof payload.scope === "string" ? payload.scope.split(" ").filter(Boolean) : []),
+        claims,
+        type: "jwt",
+        expiresAt: payload.exp ? new Date(payload.exp * 1e3) : void 0
+      };
+    }
+  });
+}
+
+// src/session-auth-interceptor.ts
+import { Code as Code7, ConnectError as ConnectError7 } from "@connectrpc/connect";
+function defaultExtractToken(req) {
+  const authHeader = req.header.get("authorization");
+  if (!authHeader) return null;
+  const match = /^Bearer\s+(.+)$/i.exec(authHeader);
+  return match?.[1] ?? null;
+}
+function createSessionAuthInterceptor(options) {
+  const { verifySession, mapSession, extractToken = defaultExtractToken, cache: cacheOptions, skipMethods = [], propagateHeaders = false, propagatedClaims } = options;
+  const cache = cacheOptions ? new LruCache(cacheOptions) : void 0;
+  return (next) => async (req) => {
+    const serviceName = req.service.typeName;
+    const methodName = req.method.name;
+    for (const headerName of Object.values(AUTH_HEADERS)) {
+      req.header.delete(headerName);
+    }
+    if (matchesMethodPattern(serviceName, methodName, skipMethods)) {
+      return await next(req);
+    }
+    const token = await extractToken(req);
+    if (!token) {
+      throw new ConnectError7("Missing credentials", Code7.Unauthenticated);
+    }
+    const cached = cache?.get(token);
+    if (cached && (!cached.expiresAt || cached.expiresAt.getTime() > Date.now())) {
+      if (propagateHeaders) {
+        setAuthHeaders(req.header, cached, propagatedClaims);
+      }
+      return await authContextStorage.run(cached, () => next(req));
+    }
+    let session;
+    try {
+      session = await verifySession(token, req.header);
+    } catch (err) {
+      if (err instanceof ConnectError7) throw err;
+      throw new ConnectError7("Session verification failed", Code7.Unauthenticated);
+    }
+    let authContext;
+    try {
+      authContext = await mapSession(session);
+    } catch (err) {
+      if (err instanceof ConnectError7) throw err;
+      throw new ConnectError7("Session mapping failed", Code7.Unauthenticated);
+    }
+    cache?.set(token, authContext);
+    if (propagateHeaders) {
+      setAuthHeaders(req.header, authContext, propagatedClaims);
+    }
+    return await authContextStorage.run(authContext, () => next(req));
+  };
+}
+export {
+  AUTH_HEADERS,
+  AuthzDeniedError,
+  AuthzEffect,
+  LruCache,
+  authContextStorage,
+  createAuthInterceptor,
+  createAuthzInterceptor,
+  createGatewayAuthInterceptor,
+  createJwtAuthInterceptor,
+  createSessionAuthInterceptor,
+  getAuthContext,
+  matchesMethodPattern,
+  parseAuthHeaders,
+  requireAuthContext,
+  setAuthHeaders
+};
+//# sourceMappingURL=index.js.map