@k9o/gate 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +9 -0
- package/LICENSE +201 -0
- package/NOTICE +4 -0
- package/README.md +270 -2
- package/dist/chunk-JEV37YEC.js +51 -0
- package/dist/chunk-JEV37YEC.js.map +1 -0
- package/dist/chunk-XP6U5QKF.js +41 -0
- package/dist/chunk-XP6U5QKF.js.map +1 -0
- package/dist/chunk-YINWOWJC.js +125 -0
- package/dist/chunk-YINWOWJC.js.map +1 -0
- package/dist/errors.d.ts +55 -0
- package/dist/errors.js +9 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +715 -0
- package/dist/index.js +613 -0
- package/dist/index.js.map +1 -0
- package/dist/jwt.d.ts +84 -0
- package/dist/jwt.js +12 -0
- package/dist/jwt.js.map +1 -0
- package/dist/mode.d.ts +82 -0
- package/dist/mode.js +13 -0
- package/dist/mode.js.map +1 -0
- package/dist/types.d.ts +250 -0
- package/dist/types.js +1 -0
- package/dist/types.js.map +1 -0
- package/package.json +59 -4
- package/src/client-factory.ts +39 -0
- package/src/client.ts +175 -0
- package/src/errors.ts +115 -0
- package/src/gate.ts +384 -0
- package/src/idp-providers/identity-providers.ts +244 -0
- package/src/index.ts +62 -0
- package/src/jwt.ts +229 -0
- package/src/magic-link-redirects.ts +103 -0
- package/src/mode.ts +115 -0
- package/src/paths.ts +21 -0
- package/src/region.ts +85 -0
- package/src/types.ts +264 -0
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import {
|
|
2
|
+
GateError
|
|
3
|
+
} from "./chunk-JEV37YEC.js";
|
|
4
|
+
|
|
5
|
+
// src/jwt.ts
|
|
6
|
+
import { createRemoteJWKSet, jwtVerify, errors as joseErrors } from "jose";
|
|
7
|
+
var DEFAULT_ALLOWED_ALGORITHMS = ["RS256", "ES256"];
|
|
8
|
+
var DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
|
|
9
|
+
async function verifyJwt(opts) {
|
|
10
|
+
if (opts.jwksUrl !== void 0 && opts.jwks !== void 0) {
|
|
11
|
+
throw new GateError({
|
|
12
|
+
code: "INVALID_FIELD_VALUE",
|
|
13
|
+
message: "verifyJwt: pass either jwksUrl OR jwks, not both",
|
|
14
|
+
context: {},
|
|
15
|
+
recommendation: null
|
|
16
|
+
});
|
|
17
|
+
}
|
|
18
|
+
if (opts.jwksUrl === void 0 && opts.jwks === void 0) {
|
|
19
|
+
throw new GateError({
|
|
20
|
+
code: "INVALID_FIELD_VALUE",
|
|
21
|
+
message: "verifyJwt: must pass exactly one of {jwksUrl, jwks}",
|
|
22
|
+
context: {},
|
|
23
|
+
recommendation: null
|
|
24
|
+
});
|
|
25
|
+
}
|
|
26
|
+
const allowedAlgorithms = opts.allowedAlgorithms ?? DEFAULT_ALLOWED_ALGORITHMS;
|
|
27
|
+
const clockTolerance = opts.clockToleranceSeconds ?? DEFAULT_CLOCK_TOLERANCE_SECONDS;
|
|
28
|
+
let keyResolver;
|
|
29
|
+
if (opts.jwksUrl !== void 0) {
|
|
30
|
+
keyResolver = createRemoteJWKSet(new URL(opts.jwksUrl));
|
|
31
|
+
} else {
|
|
32
|
+
keyResolver = makeLocalJwksResolver(opts.jwks);
|
|
33
|
+
}
|
|
34
|
+
try {
|
|
35
|
+
const result = await jwtVerify(opts.token, keyResolver, {
|
|
36
|
+
...opts.expectedIssuer !== void 0 ? { issuer: opts.expectedIssuer } : {},
|
|
37
|
+
...opts.expectedAudience !== void 0 ? { audience: opts.expectedAudience } : {},
|
|
38
|
+
algorithms: allowedAlgorithms,
|
|
39
|
+
clockTolerance
|
|
40
|
+
});
|
|
41
|
+
return { valid: true, claims: result.payload };
|
|
42
|
+
} catch (e) {
|
|
43
|
+
return { valid: false, reason: classifyJoseFailure(e) };
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
function extractClaims(token) {
|
|
47
|
+
const parts = token.split(".");
|
|
48
|
+
if (parts.length !== 3) {
|
|
49
|
+
throw new GateError({
|
|
50
|
+
code: "INVALID_FIELD_VALUE",
|
|
51
|
+
message: `Malformed JWT: expected 3 dot-separated parts, got ${parts.length}`,
|
|
52
|
+
context: {},
|
|
53
|
+
recommendation: null
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
try {
|
|
57
|
+
const payloadJson = base64UrlDecode(parts[1]);
|
|
58
|
+
return JSON.parse(payloadJson);
|
|
59
|
+
} catch (e) {
|
|
60
|
+
throw new GateError({
|
|
61
|
+
code: "INVALID_FIELD_VALUE",
|
|
62
|
+
message: `Malformed JWT payload: ${e instanceof Error ? e.message : String(e)}`,
|
|
63
|
+
context: {},
|
|
64
|
+
recommendation: null
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
function requireScope(claims, requiredScopes) {
|
|
69
|
+
const present = new Set(claims.scopes ?? []);
|
|
70
|
+
const missing = requiredScopes.filter((s) => !present.has(s));
|
|
71
|
+
if (missing.length > 0) {
|
|
72
|
+
throw new GateError({
|
|
73
|
+
code: "RBAC_DENY",
|
|
74
|
+
message: `Required scopes missing: ${missing.join(", ")}`,
|
|
75
|
+
context: { missingScopes: missing, presentScopes: Array.from(present) },
|
|
76
|
+
recommendation: null
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
function classifyJoseFailure(e) {
|
|
81
|
+
if (e instanceof joseErrors.JWSSignatureVerificationFailed) return "INVALID_SIGNATURE";
|
|
82
|
+
if (e instanceof joseErrors.JWTExpired) return "EXPIRED";
|
|
83
|
+
if (e instanceof joseErrors.JWTClaimValidationFailed) {
|
|
84
|
+
const claim = e.claim;
|
|
85
|
+
if (claim === "aud") return "AUDIENCE_MISMATCH";
|
|
86
|
+
if (claim === "iss") return "ISSUER_MISMATCH";
|
|
87
|
+
if (claim === "nbf") return "NOT_YET_VALID";
|
|
88
|
+
return "MALFORMED";
|
|
89
|
+
}
|
|
90
|
+
if (e instanceof joseErrors.JOSEAlgNotAllowed) return "ALGORITHM_NOT_ALLOWED";
|
|
91
|
+
return "MALFORMED";
|
|
92
|
+
}
|
|
93
|
+
function base64UrlDecode(input) {
|
|
94
|
+
const padded = input + "=".repeat((4 - input.length % 4) % 4);
|
|
95
|
+
const standard = padded.replace(/-/g, "+").replace(/_/g, "/");
|
|
96
|
+
const binary = globalThis.atob(standard);
|
|
97
|
+
const bytes = new Uint8Array(binary.length);
|
|
98
|
+
for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
|
|
99
|
+
return new TextDecoder("utf-8").decode(bytes);
|
|
100
|
+
}
|
|
101
|
+
function makeLocalJwksResolver(jwks) {
|
|
102
|
+
return async (header) => {
|
|
103
|
+
const { importJWK } = await import("jose");
|
|
104
|
+
const kid = header.kid;
|
|
105
|
+
let match;
|
|
106
|
+
if (kid !== void 0) {
|
|
107
|
+
match = jwks.keys.find((k) => k["kid"] === kid);
|
|
108
|
+
}
|
|
109
|
+
if (match === void 0 && jwks.keys.length === 1) {
|
|
110
|
+
match = jwks.keys[0];
|
|
111
|
+
}
|
|
112
|
+
if (match === void 0) {
|
|
113
|
+
throw new joseErrors.JWKSNoMatchingKey("No matching key in inline JWKS for kid");
|
|
114
|
+
}
|
|
115
|
+
const alg = header.alg ?? match["alg"];
|
|
116
|
+
return importJWK(match, alg);
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
export {
|
|
121
|
+
verifyJwt,
|
|
122
|
+
extractClaims,
|
|
123
|
+
requireScope
|
|
124
|
+
};
|
|
125
|
+
//# sourceMappingURL=chunk-YINWOWJC.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/jwt.ts"],"sourcesContent":["/**\n * JWT verification primitives for external-app standalone consumption.\n *\n * Standalone-mode customers consume Gate-issued JWTs in their own\n * application code without needing the full SDK shape — they just need\n * to verify the signature, extract claims, and (optionally) check\n * scopes. This module is the canonical entry for that surface.\n *\n * Backed by `jose` (already a peer dependency in the gateway via the\n * same library; chose `jose` for consistency + JWK fetch support out\n * of the box).\n *\n * Native-mode customers don't typically reach for this directly — the\n * gateway verifies project-issued tokens on every request and rehydrates\n * `subject.*` claims. But the same primitives are\n * portable: Native customers running their own services downstream of\n * the gateway can verify Gate-issued JWTs identically.\n */\n\nimport { createRemoteJWKSet, jwtVerify, errors as joseErrors } from \"jose\";\nimport type { GateJwtClaims, VerifyJwtFailure, VerifyJwtResult } from \"./types.ts\";\nimport { GateError } from \"./errors.ts\";\n\n/**\n * Configuration for `verifyJwt`. The verifier can resolve signing keys\n * via either a remote JWKS URL (the typical Gate deployment shape) or\n * an inline key set (for tests + air-gapped deployments).\n */\nexport type VerifyJwtOptions = {\n token: string;\n /**\n * JWKS endpoint URL — the gateway exposes `/@<projectSlug>/gate/.well-known/jwks.json`\n * by convention. Either `jwksUrl` or `jwks` must be set; not both.\n */\n jwksUrl?: string;\n /**\n * Inline JWK set — used by tests + integration scenarios that want to\n * avoid the network hop. The shape is the standard JWKS `{keys: [...]}`\n * envelope; pass through unchanged to `jose`.\n */\n jwks?: { keys: ReadonlyArray<Record<string, unknown>> };\n /** Expected issuer (`iss` claim). Strict comparison. */\n expectedIssuer?: string;\n /** Expected audience (`aud` claim). Accepts either string or array per RFC 7519. */\n expectedAudience?: string;\n /**\n * Allowed signing algorithms. Defaults to `[\"RS256\", \"ES256\"]` per the\n * standard Gate issuer config. Reject anything outside this set\n * (defense against alg-confusion attacks).\n */\n allowedAlgorithms?: ReadonlyArray<string>;\n /**\n * Clock-skew tolerance in seconds. Defaults to 30. Applies to both\n * `exp` and `nbf` checks.\n */\n clockToleranceSeconds?: number;\n};\n\nconst DEFAULT_ALLOWED_ALGORITHMS = [\"RS256\", \"ES256\"] as const;\nconst DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;\n\n/**\n * Verify a Gate-issued JWT. Returns a typed result; does NOT throw on\n * verification failure (a `valid: false` result carries the reason).\n *\n * Throws `GateError` only when:\n * - `jwksUrl` and `jwks` are both unset or both set\n * - the JWKS fetch fails for transport reasons (UPSTREAM_UNAVAILABLE)\n */\nexport async function verifyJwt(opts: VerifyJwtOptions): Promise<VerifyJwtResult> {\n if (opts.jwksUrl !== undefined && opts.jwks !== undefined) {\n throw new GateError({\n code: \"INVALID_FIELD_VALUE\",\n message: \"verifyJwt: pass either jwksUrl OR jwks, not both\",\n context: {},\n recommendation: null,\n });\n }\n if (opts.jwksUrl === undefined && opts.jwks === undefined) {\n throw new GateError({\n code: \"INVALID_FIELD_VALUE\",\n message: \"verifyJwt: must pass exactly one of {jwksUrl, jwks}\",\n context: {},\n recommendation: null,\n });\n }\n\n const allowedAlgorithms = opts.allowedAlgorithms ?? DEFAULT_ALLOWED_ALGORITHMS;\n const clockTolerance = opts.clockToleranceSeconds ?? DEFAULT_CLOCK_TOLERANCE_SECONDS;\n\n let keyResolver: Parameters<typeof jwtVerify>[1];\n if (opts.jwksUrl !== undefined) {\n keyResolver = createRemoteJWKSet(new URL(opts.jwksUrl));\n } else {\n // Inline JWKS — implement the resolver inline since `jose`'s\n // `createLocalJWKSet` import path varies across versions.\n keyResolver = makeLocalJwksResolver(opts.jwks!);\n }\n\n try {\n const result = await jwtVerify(opts.token, keyResolver, {\n ...(opts.expectedIssuer !== undefined ? { issuer: opts.expectedIssuer } : {}),\n ...(opts.expectedAudience !== undefined ? { audience: opts.expectedAudience } : {}),\n algorithms: allowedAlgorithms as string[],\n clockTolerance,\n });\n return { valid: true, claims: result.payload as GateJwtClaims };\n } catch (e) {\n return { valid: false, reason: classifyJoseFailure(e) };\n }\n}\n\n/**\n * Extract claims from a JWT WITHOUT verifying the signature. Used by\n * SDK consumers that want to read claim data in client code where\n * signature verification has already happened at a trusted hop (e.g.,\n * a reverse proxy). Caller is responsible for confirming the upstream\n * trust path before consuming these claims for security decisions.\n *\n * Throws `GateError` on malformed input.\n */\nexport function extractClaims(token: string): GateJwtClaims {\n const parts = token.split(\".\");\n if (parts.length !== 3) {\n throw new GateError({\n code: \"INVALID_FIELD_VALUE\",\n message: `Malformed JWT: expected 3 dot-separated parts, got ${parts.length}`,\n context: {},\n recommendation: null,\n });\n }\n try {\n const payloadJson = base64UrlDecode(parts[1]!);\n return JSON.parse(payloadJson) as GateJwtClaims;\n } catch (e) {\n throw new GateError({\n code: \"INVALID_FIELD_VALUE\",\n message: `Malformed JWT payload: ${e instanceof Error ? e.message : String(e)}`,\n context: {},\n recommendation: null,\n });\n }\n}\n\n/**\n * Assert that the given claim set contains all of the required scopes.\n * Throws `GateError` with `code: \"RBAC_DENY\"` if any scope is missing.\n * Returns nothing on success — caller uses the throw-or-pass shape.\n */\nexport function requireScope(\n claims: GateJwtClaims,\n requiredScopes: ReadonlyArray<string>,\n): void {\n const present = new Set(claims.scopes ?? []);\n const missing = requiredScopes.filter((s) => !present.has(s));\n if (missing.length > 0) {\n throw new GateError({\n code: \"RBAC_DENY\",\n message: `Required scopes missing: ${missing.join(\", \")}`,\n context: { missingScopes: missing, presentScopes: Array.from(present) },\n recommendation: null,\n });\n }\n}\n\n// ----------------------------------------------------------------------\n// Internals\n// ----------------------------------------------------------------------\n\nfunction classifyJoseFailure(e: unknown): VerifyJwtFailure {\n // Map `jose`'s typed errors to our closed reason set per `VerifyJwtFailure`.\n if (e instanceof joseErrors.JWSSignatureVerificationFailed) return \"INVALID_SIGNATURE\";\n if (e instanceof joseErrors.JWTExpired) return \"EXPIRED\";\n if (e instanceof joseErrors.JWTClaimValidationFailed) {\n const claim = (e as { claim?: string }).claim;\n if (claim === \"aud\") return \"AUDIENCE_MISMATCH\";\n if (claim === \"iss\") return \"ISSUER_MISMATCH\";\n if (claim === \"nbf\") return \"NOT_YET_VALID\";\n return \"MALFORMED\";\n }\n if (e instanceof joseErrors.JOSEAlgNotAllowed) return \"ALGORITHM_NOT_ALLOWED\";\n // Fallback — `jose` raises other errors (parse failures, KID mismatches,\n // etc.) that we lump into `MALFORMED` rather than leaking the per-version\n // taxonomy.\n return \"MALFORMED\";\n}\n\nfunction base64UrlDecode(input: string): string {\n // Pad to a multiple of 4 + swap urlsafe alphabet -> standard alphabet.\n const padded = input + \"=\".repeat((4 - (input.length % 4)) % 4);\n const standard = padded.replace(/-/g, \"+\").replace(/_/g, \"/\");\n // Bun + Node 18+ + browsers all expose `atob`.\n const binary = globalThis.atob(standard);\n // Reassemble bytes back to UTF-8 text.\n const bytes = new Uint8Array(binary.length);\n for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);\n return new TextDecoder(\"utf-8\").decode(bytes);\n}\n\n/**\n * Build a key resolver compatible with `jose.jwtVerify` from an inline\n * JWKS object. `jose` exports `createLocalJWKSet` from its main module\n * but the import path / type shape can shift across minors; reimplement\n * the minimal resolver here for stability.\n */\nfunction makeLocalJwksResolver(\n jwks: { keys: ReadonlyArray<Record<string, unknown>> },\n): Parameters<typeof jwtVerify>[1] {\n // The `jose` resolver signature is `(header, token) => Promise<KeyLike>`\n // — pull the kid from the header, match against the JWKS, and import.\n return async (header) => {\n const { importJWK } = await import(\"jose\");\n const kid = (header as { kid?: string }).kid;\n let match: Record<string, unknown> | undefined;\n if (kid !== undefined) {\n match = jwks.keys.find((k) => k[\"kid\"] === kid);\n }\n if (match === undefined && jwks.keys.length === 1) {\n // Single-key JWKS — return the only key. Tests typically ship one\n // key in the inline set and may not bother with `kid`.\n match = jwks.keys[0];\n }\n if (match === undefined) {\n throw new joseErrors.JWKSNoMatchingKey(\"No matching key in inline JWKS for kid\");\n }\n const alg = (header as { alg?: string }).alg ?? (match[\"alg\"] as string | undefined);\n return importJWK(match as unknown as Parameters<typeof importJWK>[0], alg);\n };\n}\n"],"mappings":"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","names":[]}
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Gate error shapes. `GateError` is `KError`-compatible —
|
|
3
|
+
* downstream catch blocks can `instanceof GateError`-narrow without
|
|
4
|
+
* importing the gateway's `KError` class directly (the SDK is a customer-
|
|
5
|
+
* facing dependency; reaching across to the gateway's internal error
|
|
6
|
+
* type would be a layering violation).
|
|
7
|
+
*
|
|
8
|
+
* The taxonomy below is the closed set; additions follow the
|
|
9
|
+
* error-catalogue freeze cycle.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* Closed-taxonomy error code. Strings are the wire format —
|
|
13
|
+
* camelCase-cased KError families per the convention.
|
|
14
|
+
*/
|
|
15
|
+
type GateErrorCode = "UNAUTHENTICATED" | "INVALID_FIELD_VALUE" | "EMAIL_ALREADY_REGISTERED" | "INVALID_CREDENTIALS" | "SESSION_EXPIRED" | "REFRESH_TOKEN_INVALID" | "TIER_FEATURE_GATED" | "RBAC_DENY" | "FORBIDDEN" | "NOT_FOUND" | "GATE_REDIRECT_NOT_ALLOWED" | "POLICY_AUTHORING_AUTHORITY_INSUFFICIENT" | "UPSTREAM_UNAVAILABLE" | "INTERNAL_ERROR";
|
|
16
|
+
/**
|
|
17
|
+
* Surface error thrown by the SDK. Mirrors the gateway's `KError` shape
|
|
18
|
+
* — `code` (closed taxonomy), `message` (human-readable),
|
|
19
|
+
* `context` (structured per-code payload), `recommendation` (action the
|
|
20
|
+
* caller can take, or null when there's no canonical recommendation).
|
|
21
|
+
*/
|
|
22
|
+
declare class GateError extends Error {
|
|
23
|
+
readonly code: GateErrorCode;
|
|
24
|
+
readonly context: Readonly<Record<string, unknown>>;
|
|
25
|
+
readonly recommendation: string | null;
|
|
26
|
+
/** HTTP status the gateway returned (if the error came from a wire response). */
|
|
27
|
+
readonly status: number | null;
|
|
28
|
+
constructor(init: {
|
|
29
|
+
code: GateErrorCode;
|
|
30
|
+
message: string;
|
|
31
|
+
context?: Record<string, unknown>;
|
|
32
|
+
recommendation?: string | null;
|
|
33
|
+
status?: number | null;
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Wire-shape sentinel matching the gateway's `KError` JSON payload. The
|
|
38
|
+
* client uses this to recognise gateway responses and rehydrate them
|
|
39
|
+
* into a `GateError` instance with the right code + context preserved.
|
|
40
|
+
*/
|
|
41
|
+
type KErrorWire = {
|
|
42
|
+
code: string;
|
|
43
|
+
message: string;
|
|
44
|
+
context?: Record<string, unknown>;
|
|
45
|
+
recommendation?: string | null;
|
|
46
|
+
};
|
|
47
|
+
/**
|
|
48
|
+
* Narrow a wire `KError` to a strongly-typed `GateError`. Unknown codes
|
|
49
|
+
* pass through as `INTERNAL_ERROR` with the original code preserved in
|
|
50
|
+
* `context.originalCode` so consumers don't lose telemetry when the
|
|
51
|
+
* server-side taxonomy outpaces the SDK's bundled enum.
|
|
52
|
+
*/
|
|
53
|
+
declare function gateErrorFromWire(wire: KErrorWire, status: number): GateError;
|
|
54
|
+
|
|
55
|
+
export { GateError, type GateErrorCode, type KErrorWire, gateErrorFromWire };
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
|