@stacksjs/email 0.70.302 → 0.70.304

package/dist/unsubscribe.d.ts

@@ -4,7 +4,7 @@
  * works months later, short enough that a leaked URL doesn't grant
  * indefinite control. Tighter caps available via `ttlSeconds`.
  */
-export declare function createUnsubscribeToken(email: string, ttlSeconds?: number): string;
+export declare function createUnsubscribeToken(email: string, ttlSeconds?: number, scope?: string): string;
 /**
  * Verify a signed unsubscribe token. Returns the email + a
  * discriminated outcome — callers map invalid results to a 400/410
@@ -21,7 +21,7 @@ export declare function verifyUnsubscribeToken(token: string): UnsubscribeVerifi
  * see {@link buildListUnsubscribeHeaders} for RFC 8058
  * (one-click) compatibility.
  */
-export declare function buildUnsubscribeUrl(email: string, ttlSeconds?: number, options?: { baseUrl?: string, routePrefix?: string }): string;
+export declare function buildUnsubscribeUrl(email: string, ttlSeconds?: number, options?: { baseUrl?: string, routePrefix?: string, scope?: string }): string;
 /**
  * Build a `List-Unsubscribe` / `List-Unsubscribe-Post` header
  * pair (RFC 8058). Gmail/Apple Mail use these for the native
@@ -31,9 +31,10 @@ export declare function buildUnsubscribeUrl(email: string, ttlSeconds?: number,
  * Returns a map suitable for passing into `EmailMessage.headers`
  * (or merging with existing headers).
  */
-export declare function buildListUnsubscribeHeaders(email: string, ttlSeconds?: number, options?: { baseUrl?: string, routePrefix?: string }): Record<string, string>;
+export declare function buildListUnsubscribeHeaders(email: string, ttlSeconds?: number, options?: { baseUrl?: string, routePrefix?: string, scope?: string }): Record<string, string>;
 export declare interface UnsubscribeVerification {
   valid: boolean
   reason?: 'malformed' | 'bad_signature' | 'expired'
   email?: string
+  scope?: string
 }

package/dist/unsubscribe.js

@@ -1 +1 @@
-import{createHmac,timingSafeEqual}from"node:crypto";import process from"node:process";import{Buffer}from"node:buffer";const DEFAULT_TTL_SECONDS=2592000,DEFAULT_ROUTE="/_stacks/email/unsubscribe";function getAppKey(){const k=process.env.APP_KEY;if(!k||k.length<16){if(process.env.APP_ENV==="production"||process.env.NODE_ENV==="production")throw Error("[email/unsubscribe] APP_KEY is missing or too short (need \u226516 chars). Cannot sign unsubscribe URL.")}return k||"stacks-default-key-dev-only-do-not-use-prod"}function b64UrlEncode(buf){return buf.toString("base64url")}function b64UrlDecode(s){return Buffer.from(s,"base64url")}export function createUnsubscribeToken(email,ttlSeconds=DEFAULT_TTL_SECONDS){if(!email)throw Error("[email/unsubscribe] email is required");const exp=Math.floor(Date.now()/1000)+Math.floor(ttlSeconds),claims={email:String(email).trim().toLowerCase(),exp,iss:"stacks"},payload=b64UrlEncode(Buffer.from(JSON.stringify(claims))),sig=b64UrlEncode(createHmac("sha256",getAppKey()).update(payload).digest());return`${payload}.${sig}`}export function verifyUnsubscribeToken(token){if(typeof token!=="string")return{valid:!1,reason:"malformed"};const parts=token.split(".");if(parts.length!==2)return{valid:!1,reason:"malformed"};const[payload,sig]=parts,expectedSig=createHmac("sha256",getAppKey()).update(payload).digest();let provided;try{provided=b64UrlDecode(sig)}catch{return{valid:!1,reason:"malformed"}}if(provided.length!==expectedSig.length||!timingSafeEqual(provided,expectedSig))return{valid:!1,reason:"bad_signature"};let claims;try{claims=JSON.parse(b64UrlDecode(payload).toString("utf8"))}catch{return{valid:!1,reason:"malformed"}}if(typeof claims.exp!=="number"||Math.floor(Date.now()/1000)>=claims.exp)return{valid:!1,reason:"expired"};if(!claims.email||typeof claims.email!=="string")return{valid:!1,reason:"malformed"};return{valid:!0,email:claims.email}}export function buildUnsubscribeUrl(email,ttlSeconds,options={}){const token=createUnsubscribeToken(email,ttlSeconds),base=(options.baseUrl||process.env.APP_URL||"http://localhost").replace(/\/$/,""),route=(options.routePrefix||DEFAULT_ROUTE).replace(/\/$/,"");return`${base}${route}/${token}`}export function buildListUnsubscribeHeaders(email,ttlSeconds,options){return{"List-Unsubscribe":`<${buildUnsubscribeUrl(email,ttlSeconds,options)}>`,"List-Unsubscribe-Post":"List-Unsubscribe=One-Click"}}
+import{createHmac,timingSafeEqual}from"node:crypto";import process from"node:process";import{Buffer}from"node:buffer";const DEFAULT_TTL_SECONDS=2592000,DEFAULT_ROUTE="/_stacks/email/unsubscribe";function getAppKey(){const k=process.env.APP_KEY;if(!k||k.length<16){if(process.env.APP_ENV==="production"||process.env.NODE_ENV==="production")throw Error("[email/unsubscribe] APP_KEY is missing or too short (need \u226516 chars). Cannot sign unsubscribe URL.")}return k||"stacks-default-key-dev-only-do-not-use-prod"}function b64UrlEncode(buf){return buf.toString("base64url")}function b64UrlDecode(s){return Buffer.from(s,"base64url")}export function createUnsubscribeToken(email,ttlSeconds=DEFAULT_TTL_SECONDS,scope){if(!email)throw Error("[email/unsubscribe] email is required");const exp=Math.floor(Date.now()/1000)+Math.floor(ttlSeconds),claims={email:String(email).trim().toLowerCase(),exp,iss:"stacks",...scope?{scope:String(scope)}:{}},payload=b64UrlEncode(Buffer.from(JSON.stringify(claims))),sig=b64UrlEncode(createHmac("sha256",getAppKey()).update(payload).digest());return`${payload}.${sig}`}export function verifyUnsubscribeToken(token){if(typeof token!=="string")return{valid:!1,reason:"malformed"};const parts=token.split(".");if(parts.length!==2)return{valid:!1,reason:"malformed"};const[payload,sig]=parts,expectedSig=createHmac("sha256",getAppKey()).update(payload).digest();let provided;try{provided=b64UrlDecode(sig)}catch{return{valid:!1,reason:"malformed"}}if(provided.length!==expectedSig.length||!timingSafeEqual(provided,expectedSig))return{valid:!1,reason:"bad_signature"};let claims;try{claims=JSON.parse(b64UrlDecode(payload).toString("utf8"))}catch{return{valid:!1,reason:"malformed"}}if(typeof claims.exp!=="number"||Math.floor(Date.now()/1000)>=claims.exp)return{valid:!1,reason:"expired"};if(!claims.email||typeof claims.email!=="string")return{valid:!1,reason:"malformed"};return{valid:!0,email:claims.email,...typeof claims.scope==="string"&&claims.scope?{scope:claims.scope}:{}}}export function buildUnsubscribeUrl(email,ttlSeconds,options={}){const token=createUnsubscribeToken(email,ttlSeconds,options.scope),base=(options.baseUrl||process.env.APP_URL||"http://localhost").replace(/\/$/,""),route=(options.routePrefix||DEFAULT_ROUTE).replace(/\/$/,"");return`${base}${route}/${token}`}export function buildListUnsubscribeHeaders(email,ttlSeconds,options){return{"List-Unsubscribe":`<${buildUnsubscribeUrl(email,ttlSeconds,options)}>`,"List-Unsubscribe-Post":"List-Unsubscribe=One-Click"}}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/email",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.302",
+  "version": "0.70.304",
   "description": "The Stacks Email integration. Painlessly create & manage your inboxes, templates, and send emails.",
   "author": "Chris Breuer",
   "contributors": [
@@ -63,10 +63,10 @@
     "@stacksjs/ts-cloud": "^0.7.103"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.70.302",
-    "@stacksjs/config": "0.70.302",
+    "@stacksjs/cli": "0.70.304",
+    "@stacksjs/config": "0.70.304",
     "better-dx": "^0.2.17",
-    "@stacksjs/error-handling": "0.70.302",
-    "@stacksjs/types": "0.70.302"
+    "@stacksjs/error-handling": "0.70.304",
+    "@stacksjs/types": "0.70.304"
   }
 }