@schemavaults/auth-common 0.10.11 → 0.10.15

package/dist/index.d.ts

@@ -28,3 +28,6 @@ export { determineRefreshTokenCookieSameSiteValue } from "./determineRefreshToke
 export { authorizeClientApplicationFormType } from "./authorize-client-application-form-type";
 export { paginationOptionsSchema, DEFAULT_PAGINATION_PAGE_INDEX, DEFAULT_PAGINATION_PAGE_SIZE, isValidPaginationOptions, } from "./pagination";
 export type { PaginationOptions } from "./pagination";
+export { timingSafeStringEqual } from "./timing-safe-string-equal";
+export { oauth2StateSchema, OAUTH2_STATE_VSCHAR_REGEX, parseOAuth2State, OAuth2StateValidationError, } from "./oauth2-state-schema";
+export type { OAuth2State } from "./oauth2-state-schema";

package/dist/index.js

@@ -19,4 +19,6 @@ export { AccessTokenCookieName, AccessTokenExpiryCookieName, } from "./AccessTok
 export { determineRefreshTokenCookieSameSiteValue } from "./determineRefreshTokenCookieSameSiteValue";
 export { authorizeClientApplicationFormType } from "./authorize-client-application-form-type";
 export { paginationOptionsSchema, DEFAULT_PAGINATION_PAGE_INDEX, DEFAULT_PAGINATION_PAGE_SIZE, isValidPaginationOptions, } from "./pagination";
+export { timingSafeStringEqual } from "./timing-safe-string-equal";
+export { oauth2StateSchema, OAUTH2_STATE_VSCHAR_REGEX, parseOAuth2State, OAuth2StateValidationError, } from "./oauth2-state-schema";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,GACf,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,cAAc,EAAiB,MAAM,aAAa,CAAC;AAE5D,cAAc,eAAe,CAAC;AAG9B,mBAAmB;AACnB,cAAc,cAAc,CAAC;AAM7B,cAAc,cAAc,CAAC;AAG7B,cAAc,QAAQ,CAAC;AAGvB,OAAO,EACL,wBAAwB,GAEzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,yBAAyB,EAEzB,uCAAuC,GAExC,MAAM,yBAAyB,CAAC;AAEjC,cAAc,mCAAmC,CAAC;AAGlD,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,EACL,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,aAAa,EACb,4BAA4B,EAC5B,0BAA0B,EAC1B,8BAA8B,EAC9B,8BAA8B,EAC9B,sBAAsB,EACtB,sBAAsB,EACtB,iCAAiC,EACjC,kCAAkC,EAClC,4BAA4B,EAC5B,+BAA+B,EAC/B,oCAAoC,EACpC,qCAAqC,GACtC,MAAM,iBAAiB,CAAC;AAczB,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,OAAO,EACL,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,wCAAwC,EAAE,MAAM,4CAA4C,CAAC;AAEtG,OAAO,EAAE,kCAAkC,EAAE,MAAM,0CAA0C,CAAC;AAE9F,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,cAAc,GACf,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,cAAc,EAAiB,MAAM,aAAa,CAAC;AAE5D,cAAc,eAAe,CAAC;AAG9B,mBAAmB;AACnB,cAAc,cAAc,CAAC;AAM7B,cAAc,cAAc,CAAC;AAG7B,cAAc,QAAQ,CAAC;AAGvB,OAAO,EACL,wBAAwB,GAEzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,yBAAyB,EAEzB,uCAAuC,GAExC,MAAM,yBAAyB,CAAC;AAEjC,cAAc,mCAAmC,CAAC;AAGlD,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,EACL,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,aAAa,EACb,4BAA4B,EAC5B,0BAA0B,EAC1B,8BAA8B,EAC9B,8BAA8B,EAC9B,sBAAsB,EACtB,sBAAsB,EACtB,iCAAiC,EACjC,kCAAkC,EAClC,4BAA4B,EAC5B,+BAA+B,EAC/B,oCAAoC,EACpC,qCAAqC,GACtC,MAAM,iBAAiB,CAAC;AAczB,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,OAAO,EACL,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,wCAAwC,EAAE,MAAM,4CAA4C,CAAC;AAEtG,OAAO,EAAE,kCAAkC,EAAE,MAAM,0CAA0C,CAAC;AAE9F,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EACL,iBAAiB,EACjB,yBAAyB,EACzB,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC"}

package/dist/oauth2-state-schema.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export declare const OAUTH2_STATE_VSCHAR_REGEX: RegExp;
+export declare const oauth2StateSchema: z.ZodString;
+export type OAuth2State = z.infer<typeof oauth2StateSchema>;
+/**
+ * Thrown by `parseOAuth2State` when the caller supplied a `state`
+ * value that is present but fails schema validation. Callers at
+ * server-side entry points should turn this into a 400 response
+ * (e.g. `redirectWithError(400, "bad_request")` for page routes,
+ * `NextResponse.json(..., { status: 400 })` for API routes).
+ */
+export declare class OAuth2StateValidationError extends Error {
+    readonly reasons: readonly string[];
+    constructor(reasons: readonly string[]);
+}
+/**
+ * Validates an OAuth2 `state` at a server boundary.
+ *
+ *   - Absent / null / undefined → returns `null` (RFC-legal; `state`
+ *     is optional).
+ *   - Present + well-formed → returns the validated string.
+ *   - Present + malformed (wrong type, empty, too long, non-VSCHAR)
+ *     → throws `OAuth2StateValidationError` so the caller can 400.
+ *
+ * Empty strings are treated as malformed (not absent) so a client
+ * that accidentally serializes `?state=` gets a loud signal instead
+ * of a silent downgrade.
+ */
+export declare function parseOAuth2State(raw: unknown): string | null;

package/dist/oauth2-state-schema.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+// RFC 6749 §10.12 introduces the OAuth2 `state` parameter as a
+// client-side CSRF nonce. RFC 6749 §A.5 defines its on-the-wire form
+// as `*VSCHAR` — zero or more printable ASCII characters %x20-%x7E.
+// The auth server never interprets `state`; it only echoes the value
+// untouched on the callback. The validator below therefore captures
+// only the properties worth enforcing at the protocol boundary:
+//
+//   1. Non-empty (a zero-length state has no CSRF value).
+//   2. Bounded length — 512 chars is comfortably above common shapes
+//      (UUID, base64url 32-byte nonce, short signed JWTs) while
+//      protecting log pipelines and callback-URL buffers from
+//      unbounded echo.
+//   3. Printable ASCII only — prevents log-pollution / terminal-escape
+//      smuggling via control chars, NULs, and CR/LF.
+//
+// This schema is deliberately not base64url-specific: that would be
+// SDK-opinionated and would break RFC-legal third-party clients that
+// use UUIDs, signed JWTs, or other formats for their state value.
+const MAX_OAUTH2_STATE_LENGTH = 512;
+export const OAUTH2_STATE_VSCHAR_REGEX = /^[\x20-\x7E]+$/;
+export const oauth2StateSchema = z
+    .string()
+    .min(1)
+    .max(MAX_OAUTH2_STATE_LENGTH)
+    .regex(OAUTH2_STATE_VSCHAR_REGEX, {
+    message: "OAuth2 'state' must contain only printable ASCII (RFC 6749 §A.5 VSCHAR)",
+});
+/**
+ * Thrown by `parseOAuth2State` when the caller supplied a `state`
+ * value that is present but fails schema validation. Callers at
+ * server-side entry points should turn this into a 400 response
+ * (e.g. `redirectWithError(400, "bad_request")` for page routes,
+ * `NextResponse.json(..., { status: 400 })` for API routes).
+ */
+export class OAuth2StateValidationError extends Error {
+    reasons;
+    constructor(reasons) {
+        super(`Invalid OAuth2 'state' parameter: ${reasons.join("; ")}`);
+        this.name = "OAuth2StateValidationError";
+        this.reasons = reasons;
+    }
+}
+/**
+ * Validates an OAuth2 `state` at a server boundary.
+ *
+ *   - Absent / null / undefined → returns `null` (RFC-legal; `state`
+ *     is optional).
+ *   - Present + well-formed → returns the validated string.
+ *   - Present + malformed (wrong type, empty, too long, non-VSCHAR)
+ *     → throws `OAuth2StateValidationError` so the caller can 400.
+ *
+ * Empty strings are treated as malformed (not absent) so a client
+ * that accidentally serializes `?state=` gets a loud signal instead
+ * of a silent downgrade.
+ */
+export function parseOAuth2State(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== "string") {
+        throw new OAuth2StateValidationError([
+            `Expected string, got ${Array.isArray(raw) ? "array" : typeof raw}`,
+        ]);
+    }
+    const parsed = oauth2StateSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new OAuth2StateValidationError(parsed.error.issues.map((i) => i.message));
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=oauth2-state-schema.js.map

package/dist/oauth2-state-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2-state-schema.js","sourceRoot":"","sources":["../src/oauth2-state-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+DAA+D;AAC/D,qEAAqE;AACrE,oEAAoE;AACpE,qEAAqE;AACrE,oEAAoE;AACpE,gEAAgE;AAChE,EAAE;AACF,0DAA0D;AAC1D,qEAAqE;AACrE,gEAAgE;AAChE,8DAA8D;AAC9D,uBAAuB;AACvB,uEAAuE;AACvE,qDAAqD;AACrD,EAAE;AACF,oEAAoE;AACpE,qEAAqE;AACrE,kEAAkE;AAElE,MAAM,uBAAuB,GAAG,GAAY,CAAC;AAE7C,MAAM,CAAC,MAAM,yBAAyB,GAAW,gBAAgB,CAAC;AAElE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,uBAAuB,CAAC;KAC5B,KAAK,CAAC,yBAAyB,EAAE;IAChC,OAAO,EACL,yEAAyE;CAC5E,CAAC,CAAC;AAIL;;;;;;GAMG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACnC,OAAO,CAAoB;IAC3C,YAAmB,OAA0B;QAC3C,KAAK,CAAC,qCAAqC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,0BAA0B,CAAC;YACnC,wBAAwB,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,GAAG,EAAE;SACpE,CAAC,CAAC;IACL,CAAC;IACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,0BAA0B,CAClC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAC1C,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/timing-safe-string-equal.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Timing-safe string comparison usable from browser bundles.
+ *
+ * `node:crypto.timingSafeEqual` is Node-only; this pure-JS variant
+ * operates on strings and runs in both browser and server contexts.
+ * Not strictly constant-time under every JIT, but avoids early-exit on
+ * the first byte of divergence — strictly better than `===` for
+ * CSRF-nonce / token comparison.
+ *
+ * Returns false on any non-string input or length mismatch.
+ */
+export declare function timingSafeStringEqual(a: string, b: string): boolean;
+export default timingSafeStringEqual;

package/dist/timing-safe-string-equal.js

@@ -0,0 +1,24 @@
+/**
+ * Timing-safe string comparison usable from browser bundles.
+ *
+ * `node:crypto.timingSafeEqual` is Node-only; this pure-JS variant
+ * operates on strings and runs in both browser and server contexts.
+ * Not strictly constant-time under every JIT, but avoids early-exit on
+ * the first byte of divergence — strictly better than `===` for
+ * CSRF-nonce / token comparison.
+ *
+ * Returns false on any non-string input or length mismatch.
+ */
+export function timingSafeStringEqual(a, b) {
+    if (typeof a !== "string" || typeof b !== "string")
+        return false;
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return diff === 0;
+}
+export default timingSafeStringEqual;
+//# sourceMappingURL=timing-safe-string-equal.js.map

package/dist/timing-safe-string-equal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing-safe-string-equal.js","sourceRoot":"","sources":["../src/timing-safe-string-equal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAS,EAAE,CAAS;IACxD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACjE,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,eAAe,qBAAqB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schemavaults/auth-common",
   "description": "Types and utility functions for authentication and authorization",
-  "version": "0.10.11",
+  "version": "0.10.15",
   "license": "UNLICENSED",
   "private": false,
   "repository": {