@cedarjs/api 7.0.0-canary.3111 → 7.0.0-canary.3113

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './types.js';
 export * from './transforms.js';
 export * from './cors.js';
 export * from './event.js';
+export * from './signedTokens/index.js';
 export declare const prismaVersion: string | undefined;
 /** @deprecated - use `cedarVersion` instead */
 export declare const redwoodVersion: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,8BAA8B,CAAA;AAC5C,cAAc,yBAAyB,CAAA;AACvC,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAU1B,eAAO,MAAM,aAAa,EAAE,MAAM,GAAG,SAAqC,CAAA;AAC1E,+CAA+C;AAC/C,eAAO,MAAM,cAAc,QAAwB,CAAA;AACnD,+CAA+C;AAC/C,eAAO,MAAM,cAAc,QAAwB,CAAA;AACnD,eAAO,MAAM,YAAY,QAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,8BAA8B,CAAA;AAC5C,cAAc,yBAAyB,CAAA;AACvC,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AAUvC,eAAO,MAAM,aAAa,EAAE,MAAM,GAAG,SAAqC,CAAA;AAC1E,+CAA+C;AAC/C,eAAO,MAAM,cAAc,QAAwB,CAAA;AACnD,+CAA+C;AAC/C,eAAO,MAAM,cAAc,QAAwB,CAAA;AACnD,eAAO,MAAM,YAAY,QAAwB,CAAA"}

package/dist/index.js

@@ -6,10 +6,11 @@ export * from "./types.js";
 export * from "./transforms.js";
 export * from "./cors.js";
 export * from "./event.js";
+export * from "./signedTokens/index.js";
 const prismaVersion = "7.10.0";
-const redwoodVersion = "7.0.0-canary.3111";
-const cedarjsVersion = "7.0.0-canary.3111";
-const cedarVersion = "7.0.0-canary.3111";
+const redwoodVersion = "7.0.0-canary.3113";
+const cedarjsVersion = "7.0.0-canary.3113";
+const cedarVersion = "7.0.0-canary.3113";
 export {
   cedarVersion,
   cedarjsVersion,

package/dist/signedTokens/index.d.ts

@@ -0,0 +1,2 @@
+export * from './signedTokens.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/signedTokens/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/signedTokens/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA"}

package/dist/signedTokens/index.js

@@ -0,0 +1 @@
+export * from "./signedTokens.js";

package/dist/signedTokens/signedTokens.d.ts

@@ -0,0 +1,99 @@
+import type { SignOptions } from 'jsonwebtoken';
+/**
+ * Name of the environment variable that holds the default secret used to
+ * sign and verify tokens when no `secret` option is passed.
+ */
+export declare const SIGNED_TOKEN_SECRET_ENV_VAR = "SIGNED_TOKEN_SECRET";
+/**
+ * Machine-readable reason a `SignedTokenError` was thrown. Use it to tell an
+ * expired link apart from a tampered one without matching on the message.
+ */
+export type SignedTokenErrorCode = 'MISSING_SECRET' | 'MISSING_PURPOSE' | 'MISSING_TOKEN' | 'SIGN_FAILED' | 'INVALID' | 'EXPIRED' | 'PURPOSE_MISMATCH';
+/**
+ * Thrown by `createSignedToken` and `verifySignedToken` whenever a token
+ * cannot be created or cannot be trusted. Verification never returns `null`
+ * or `false` for a bad token; it always throws so a missing check cannot
+ * silently pass.
+ */
+export declare class SignedTokenError extends Error {
+    code: SignedTokenErrorCode;
+    constructor(code: SignedTokenErrorCode, message: string, cause?: unknown);
+}
+/**
+ * How long a token stays valid. A number is a count of seconds. A string is
+ * a duration such as `'10m'`, `'2h'`, or `'7 days'`.
+ */
+export type SignedTokenExpiresIn = NonNullable<SignOptions['expiresIn']>;
+export interface CreateSignedTokenOptions<TPayload extends object> {
+    /**
+     * The claims to carry inside the token. Serialized as JSON, so only
+     * JSON-compatible values survive the round trip (a `Date` comes back as a
+     * string).
+     */
+    payload: TPayload;
+    /**
+     * What the token is for, such as `'google-oauth-state'` or
+     * `'email-confirmation'`. A token only verifies when the same purpose is
+     * passed to `verifySignedToken`, so a token minted for one flow cannot be
+     * replayed in another.
+     */
+    purpose: string;
+    /** How long the token stays valid. See `SignedTokenExpiresIn`. */
+    expiresIn: SignedTokenExpiresIn;
+    /**
+     * The secret to sign with. Defaults to the `SIGNED_TOKEN_SECRET`
+     * environment variable. There is no built-in fallback: when neither is set
+     * a `SignedTokenError` with code `MISSING_SECRET` is thrown.
+     */
+    secret?: string;
+}
+export interface VerifySignedTokenOptions {
+    /** The purpose the token must have been created with. */
+    purpose: string;
+    /**
+     * The secret to verify with. Defaults to the `SIGNED_TOKEN_SECRET`
+     * environment variable. There is no built-in fallback: when neither is set
+     * a `SignedTokenError` with code `MISSING_SECRET` is thrown.
+     */
+    secret?: string;
+}
+/**
+ * Creates a compact, URL-safe token that carries `payload`, is bound to
+ * `purpose`, expires after `expiresIn`, and is signed so it can only have
+ * come from this application.
+ *
+ * Use it wherever a value has to leave the server and come back untouched:
+ * OAuth `state`, email confirmation and password-set links, unsubscribe
+ * links, or short-lived capability tokens.
+ *
+ * @example
+ *
+ *    const state = createSignedToken({
+ *      payload: { organizationId, userId },
+ *      purpose: 'google-oauth-state',
+ *      expiresIn: '10m',
+ *    })
+ */
+export declare function createSignedToken<TPayload extends object>({ payload, purpose, expiresIn, secret, }: CreateSignedTokenOptions<TPayload>): string;
+/**
+ * Verifies a token created by `createSignedToken` and returns its payload.
+ *
+ * Throws a `SignedTokenError` when the token is missing, was signed with a
+ * different secret, has been tampered with, has expired, or was created for
+ * a different `purpose`. The error's `code` says which.
+ *
+ * The token argument accepts `null` and `undefined` on purpose so a value
+ * read straight from a query string or a header can be passed in as-is. A
+ * missing token is a verification failure, never a skipped check.
+ *
+ * @example
+ *
+ *    const { organizationId, userId } = verifySignedToken<{
+ *      organizationId: string
+ *      userId: string
+ *    }>(event.queryStringParameters?.state, {
+ *      purpose: 'google-oauth-state',
+ *    })
+ */
+export declare function verifySignedToken<TPayload extends object = Record<string, unknown>>(token: string | null | undefined, { purpose, secret }: VerifySignedTokenOptions): TPayload;
+//# sourceMappingURL=signedTokens.d.ts.map

package/dist/signedTokens/signedTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signedTokens.d.ts","sourceRoot":"","sources":["../../src/signedTokens/signedTokens.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C;;;GAGG;AACH,eAAO,MAAM,2BAA2B,wBAAwB,CAAA;AAEhE;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC5B,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,GACf,aAAa,GACb,SAAS,GACT,SAAS,GACT,kBAAkB,CAAA;AAEtB;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,IAAI,EAAE,oBAAoB,CAAA;gBAEd,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAKzE;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAA;AAExE,MAAM,WAAW,wBAAwB,CAAC,QAAQ,SAAS,MAAM;IAC/D;;;;OAIG;IACH,OAAO,EAAE,QAAQ,CAAA;IACjB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,SAAS,EAAE,oBAAoB,CAAA;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAiED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,SAAS,MAAM,EAAE,EACzD,OAAO,EACP,OAAO,EACP,SAAS,EACT,MAAM,GACP,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAAG,MAAM,CAkB7C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjD,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,wBAAwB,GAC5C,QAAQ,CA2CV"}

package/dist/signedTokens/signedTokens.js

@@ -0,0 +1,100 @@
+import jwt from "jsonwebtoken";
+const SIGNED_TOKEN_SECRET_ENV_VAR = "SIGNED_TOKEN_SECRET";
+class SignedTokenError extends Error {
+  code;
+  constructor(code, message, cause) {
+    super(message, cause === void 0 ? void 0 : { cause });
+    this.name = "SignedTokenError";
+    this.code = code;
+  }
+}
+const ALGORITHM = "HS256";
+function resolveSecret(secret, action) {
+  const resolved = secret ?? process.env[SIGNED_TOKEN_SECRET_ENV_VAR];
+  if (typeof resolved === "string" && resolved.length > 0) {
+    return resolved;
+  }
+  throw new SignedTokenError(
+    "MISSING_SECRET",
+    `Cannot ${action} a signed token because no secret is configured. Set the ${SIGNED_TOKEN_SECRET_ENV_VAR} environment variable (generate a value with \`yarn cedar generate secret\`), or pass the \`secret\` option explicitly.`
+  );
+}
+function assertPurpose(purpose) {
+  if (typeof purpose === "string" && purpose.length > 0) {
+    return;
+  }
+  throw new SignedTokenError(
+    "MISSING_PURPOSE",
+    "A signed token needs a non-empty `purpose` string, such as 'google-oauth-state' or 'email-confirmation'. The purpose is what stops a token created for one flow from verifying in another."
+  );
+}
+function isSignedTokenClaims(claims) {
+  if (typeof claims !== "object" || claims === null) {
+    return false;
+  }
+  if (!("payload" in claims) || !("purpose" in claims) || !("exp" in claims)) {
+    return false;
+  }
+  return typeof claims.payload === "object" && claims.payload !== null && typeof claims.purpose === "string" && typeof claims.exp === "number";
+}
+function createSignedToken({
+  payload,
+  purpose,
+  expiresIn,
+  secret
+}) {
+  assertPurpose(purpose);
+  const resolvedSecret = resolveSecret(secret, "create");
+  try {
+    return jwt.sign({ payload, purpose }, resolvedSecret, {
+      algorithm: ALGORITHM,
+      expiresIn
+    });
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new SignedTokenError(
+      "SIGN_FAILED",
+      `Could not create signed token: ${message}`,
+      e
+    );
+  }
+}
+function verifySignedToken(token, { purpose, secret }) {
+  assertPurpose(purpose);
+  const resolvedSecret = resolveSecret(secret, "verify");
+  if (typeof token !== "string" || token.length === 0) {
+    throw new SignedTokenError("MISSING_TOKEN", "No signed token was provided.");
+  }
+  let claims;
+  try {
+    claims = jwt.verify(token, resolvedSecret, { algorithms: [ALGORITHM] });
+  } catch (e) {
+    if (e instanceof jwt.TokenExpiredError) {
+      throw new SignedTokenError("EXPIRED", "The signed token has expired.", e);
+    }
+    throw new SignedTokenError(
+      "INVALID",
+      "The signed token is invalid or was not created by this application.",
+      e
+    );
+  }
+  if (!isSignedTokenClaims(claims)) {
+    throw new SignedTokenError(
+      "INVALID",
+      "The signed token is invalid or was not created by this application."
+    );
+  }
+  if (claims.purpose !== purpose) {
+    throw new SignedTokenError(
+      "PURPOSE_MISMATCH",
+      `The signed token was created for purpose '${claims.purpose}' but was verified with purpose '${purpose}'.`
+    );
+  }
+  return claims.payload;
+}
+export {
+  SIGNED_TOKEN_SECRET_ENV_VAR,
+  SignedTokenError,
+  createSignedToken,
+  verifySignedToken
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cedarjs/api",
-  "version": "7.0.0-canary.3111",
+  "version": "7.0.0-canary.3113",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cedarjs/cedar.git",
@@ -84,7 +84,7 @@
     "title-case": "3.0.3"
   },
   "devDependencies": {
-    "@cedarjs/framework-tools": "7.0.0-canary.3111",
+    "@cedarjs/framework-tools": "7.0.0-canary.3113",
     "@types/aws-lambda": "8.10.163",
     "@types/jsonwebtoken": "9.0.10",
     "@types/memjs": "1",