@dbx-tools/shared-email 0.6.40 → 0.6.42

package/index.ts

@@ -2,6 +2,9 @@
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
 
+export * as auth from "./src/auth.ts";
 export * as email from "./src/email.ts";
+export { authRequestSchema, authRequestResultSchema, authVerifySchema, authVerifyResultSchema, authStatusSchema } from "./src/auth.ts";
+export type { AuthRequest, AuthRequestResult, AuthVerify, AuthVerifyResult, AuthStatus } from "./src/auth.ts";
 export { emailAttachmentSchema, emailMessageSchema, emailResultSchema, emailSendersSchema } from "./src/email.ts";
 export type { EmailAttachment, EmailMessage, EmailResult, EmailSenders } from "./src/email.ts";

package/lib/index.d.ts

@@ -1,3 +1,6 @@
+export * as auth from "./src/auth.ts";
 export * as email from "./src/email.ts";
+export { authRequestSchema, authRequestResultSchema, authVerifySchema, authVerifyResultSchema, authStatusSchema } from "./src/auth.ts";
+export type { AuthRequest, AuthRequestResult, AuthVerify, AuthVerifyResult, AuthStatus } from "./src/auth.ts";
 export { emailAttachmentSchema, emailMessageSchema, emailResultSchema, emailSendersSchema } from "./src/email.ts";
 export type { EmailAttachment, EmailMessage, EmailResult, EmailSenders } from "./src/email.ts";

package/lib/index.js

@@ -1,6 +1,8 @@
 // GENERATED by projen watch - DO NOT EDIT.
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
+export * as auth from "./src/auth.js";
 export * as email from "./src/email.js";
+export { authRequestSchema, authRequestResultSchema, authVerifySchema, authVerifyResultSchema, authStatusSchema } from "./src/auth.js";
 export { emailAttachmentSchema, emailMessageSchema, emailResultSchema, emailSendersSchema } from "./src/email.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSxrQkFBa0IsRUFBRSxpQkFBaUIsRUFBRSxrQkFBa0IsRUFBRSxNQUFNLGdCQUFnQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0ICogYXMgZW1haWwgZnJvbSBcIi4vc3JjL2VtYWlsLnRzXCI7XG5leHBvcnQgeyBlbWFpbEF0dGFjaG1lbnRTY2hlbWEsIGVtYWlsTWVzc2FnZVNjaGVtYSwgZW1haWxSZXN1bHRTY2hlbWEsIGVtYWlsU2VuZGVyc1NjaGVtYSB9IGZyb20gXCIuL3NyYy9lbWFpbC50c1wiO1xuZXhwb3J0IHR5cGUgeyBFbWFpbEF0dGFjaG1lbnQsIEVtYWlsTWVzc2FnZSwgRW1haWxSZXN1bHQsIEVtYWlsU2VuZGVycyB9IGZyb20gXCIuL3NyYy9lbWFpbC50c1wiO1xuIl19
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssSUFBSSxNQUFNLGVBQWUsQ0FBQztBQUN0QyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSx1QkFBdUIsRUFBRSxnQkFBZ0IsRUFBRSxzQkFBc0IsRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLGVBQWUsQ0FBQztBQUV2SSxPQUFPLEVBQUUscUJBQXFCLEVBQUUsa0JBQWtCLEVBQUUsaUJBQWlCLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCAqIGFzIGF1dGggZnJvbSBcIi4vc3JjL2F1dGgudHNcIjtcbmV4cG9ydCAqIGFzIGVtYWlsIGZyb20gXCIuL3NyYy9lbWFpbC50c1wiO1xuZXhwb3J0IHsgYXV0aFJlcXVlc3RTY2hlbWEsIGF1dGhSZXF1ZXN0UmVzdWx0U2NoZW1hLCBhdXRoVmVyaWZ5U2NoZW1hLCBhdXRoVmVyaWZ5UmVzdWx0U2NoZW1hLCBhdXRoU3RhdHVzU2NoZW1hIH0gZnJvbSBcIi4vc3JjL2F1dGgudHNcIjtcbmV4cG9ydCB0eXBlIHsgQXV0aFJlcXVlc3QsIEF1dGhSZXF1ZXN0UmVzdWx0LCBBdXRoVmVyaWZ5LCBBdXRoVmVyaWZ5UmVzdWx0LCBBdXRoU3RhdHVzIH0gZnJvbSBcIi4vc3JjL2F1dGgudHNcIjtcbmV4cG9ydCB7IGVtYWlsQXR0YWNobWVudFNjaGVtYSwgZW1haWxNZXNzYWdlU2NoZW1hLCBlbWFpbFJlc3VsdFNjaGVtYSwgZW1haWxTZW5kZXJzU2NoZW1hIH0gZnJvbSBcIi4vc3JjL2VtYWlsLnRzXCI7XG5leHBvcnQgdHlwZSB7IEVtYWlsQXR0YWNobWVudCwgRW1haWxNZXNzYWdlLCBFbWFpbFJlc3VsdCwgRW1haWxTZW5kZXJzIH0gZnJvbSBcIi4vc3JjL2VtYWlsLnRzXCI7XG4iXX0=

package/lib/src/auth.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Wire-format contract for the email one-time-password ACCESS GATE.
+ *
+ * A companion to the email add-on's send contract ({@link ./email}): where that
+ * lets an agent send mail, this lets an AppKit app put an email-OTP gate in front
+ * of itself - the login flow for an app exposed publicly (e.g. through a portr
+ * tunnel that bypasses the Databricks front door). Pure zod so the server routes,
+ * the React `AuthGate`, and any client validate against one definition.
+ *
+ * Flow: `POST /request` (email) -> a 6-digit code is emailed -> `POST /verify`
+ * (email + code) -> an HttpOnly session cookie is set -> `GET /status` reports
+ * whether the caller is authenticated. `request` ALWAYS reports success (the
+ * server never reveals whether an address is allow-listed or was actually sent a
+ * code - anti-enumeration).
+ *
+ * @module
+ */
+import { z } from "zod";
+/** `POST /api/email/auth/request` body: ask for a code to be emailed. */
+export declare const authRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+}, z.core.$strip>;
+/** {@link authRequestSchema} */
+export type AuthRequest = z.infer<typeof authRequestSchema>;
+/**
+ * `POST /api/email/auth/request` response. Always `{ ok: true }` on a
+ * well-formed request, regardless of whether the address was allowed or a code
+ * was actually sent - the client cannot distinguish an allowed address from a
+ * rejected one (anti-enumeration). `retryAfter` is set only when the caller is
+ * rate-limited, so a UI can show a cooldown without leaking allow-list state.
+ */
+export declare const authRequestResultSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    retryAfter: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** {@link authRequestResultSchema} */
+export type AuthRequestResult = z.infer<typeof authRequestResultSchema>;
+/** `POST /api/email/auth/verify` body: submit the emailed code. */
+export declare const authVerifySchema: z.ZodObject<{
+    email: z.ZodString;
+    code: z.ZodString;
+}, z.core.$strip>;
+/** {@link authVerifySchema} */
+export type AuthVerify = z.infer<typeof authVerifySchema>;
+/**
+ * `POST /api/email/auth/verify` response. `ok` true means the code matched and
+ * an HttpOnly session cookie was set; false means it did not (wrong, expired, or
+ * too many attempts) - the message is deliberately generic. `retryAfter` is set
+ * when the failure was a rate limit.
+ */
+export declare const authVerifyResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    retryAfter: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** {@link authVerifyResultSchema} */
+export type AuthVerifyResult = z.infer<typeof authVerifyResultSchema>;
+/** `GET /api/email/auth/status` response: is the caller authenticated, and as whom. */
+export declare const authStatusSchema: z.ZodObject<{
+    authenticated: z.ZodBoolean;
+    email: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodBoolean;
+}, z.core.$strip>;
+/** {@link authStatusSchema} */
+export type AuthStatus = z.infer<typeof authStatusSchema>;

package/lib/src/auth.js

@@ -0,0 +1,60 @@
+/**
+ * Wire-format contract for the email one-time-password ACCESS GATE.
+ *
+ * A companion to the email add-on's send contract ({@link ./email}): where that
+ * lets an agent send mail, this lets an AppKit app put an email-OTP gate in front
+ * of itself - the login flow for an app exposed publicly (e.g. through a portr
+ * tunnel that bypasses the Databricks front door). Pure zod so the server routes,
+ * the React `AuthGate`, and any client validate against one definition.
+ *
+ * Flow: `POST /request` (email) -> a 6-digit code is emailed -> `POST /verify`
+ * (email + code) -> an HttpOnly session cookie is set -> `GET /status` reports
+ * whether the caller is authenticated. `request` ALWAYS reports success (the
+ * server never reveals whether an address is allow-listed or was actually sent a
+ * code - anti-enumeration).
+ *
+ * @module
+ */
+import { z } from "zod";
+/** `POST /api/email/auth/request` body: ask for a code to be emailed. */
+export const authRequestSchema = z.object({
+    email: z.string().describe("Address to email a one-time code to, if it is allowed."),
+});
+/**
+ * `POST /api/email/auth/request` response. Always `{ ok: true }` on a
+ * well-formed request, regardless of whether the address was allowed or a code
+ * was actually sent - the client cannot distinguish an allowed address from a
+ * rejected one (anti-enumeration). `retryAfter` is set only when the caller is
+ * rate-limited, so a UI can show a cooldown without leaking allow-list state.
+ */
+export const authRequestResultSchema = z.object({
+    ok: z.literal(true).describe("Always true for a well-formed request (anti-enumeration)."),
+    retryAfter: z
+        .number()
+        .optional()
+        .describe("Seconds to wait before requesting again, when rate-limited."),
+});
+/** `POST /api/email/auth/verify` body: submit the emailed code. */
+export const authVerifySchema = z.object({
+    email: z.string().describe("The address the code was requested for."),
+    code: z.string().describe("The one-time code from the email."),
+});
+/**
+ * `POST /api/email/auth/verify` response. `ok` true means the code matched and
+ * an HttpOnly session cookie was set; false means it did not (wrong, expired, or
+ * too many attempts) - the message is deliberately generic. `retryAfter` is set
+ * when the failure was a rate limit.
+ */
+export const authVerifyResultSchema = z.object({
+    ok: z.boolean().describe("True when the code matched and a session was established."),
+    retryAfter: z.number().optional().describe("Seconds to wait before retrying, when rate-limited."),
+});
+/** `GET /api/email/auth/status` response: is the caller authenticated, and as whom. */
+export const authStatusSchema = z.object({
+    authenticated: z.boolean().describe("True when the request carries a valid session."),
+    email: z.string().optional().describe("The authenticated address, when authenticated."),
+    enabled: z
+        .boolean()
+        .describe("True when the gate is active; false means the app is open (no login needed)."),
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXV0aC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9hdXRoLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7O0dBZ0JHO0FBRUgsT0FBTyxFQUFFLENBQUMsRUFBRSxNQUFNLEtBQUssQ0FBQztBQUV4Qix5RUFBeUU7QUFDekUsTUFBTSxDQUFDLE1BQU0saUJBQWlCLEdBQUcsQ0FBQyxDQUFDLE1BQU0sQ0FBQztJQUN4QyxLQUFLLEVBQUUsQ0FBQyxDQUFDLE1BQU0sRUFBRSxDQUFDLFFBQVEsQ0FBQyx3REFBd0QsQ0FBQztDQUNyRixDQUFDLENBQUM7QUFLSDs7Ozs7O0dBTUc7QUFDSCxNQUFNLENBQUMsTUFBTSx1QkFBdUIsR0FBRyxDQUFDLENBQUMsTUFBTSxDQUFDO0lBQzlDLEVBQUUsRUFBRSxDQUFDLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDLFFBQVEsQ0FBQywyREFBMkQsQ0FBQztJQUN6RixVQUFVLEVBQUUsQ0FBQztTQUNWLE1BQU0sRUFBRTtTQUNSLFFBQVEsRUFBRTtTQUNWLFFBQVEsQ0FBQyw2REFBNkQsQ0FBQztDQUMzRSxDQUFDLENBQUM7QUFLSCxtRUFBbUU7QUFDbkUsTUFBTSxDQUFDLE1BQU0sZ0JBQWdCLEdBQUcsQ0FBQyxDQUFDLE1BQU0sQ0FBQztJQUN2QyxLQUFLLEVBQUUsQ0FBQyxDQUFDLE1BQU0sRUFBRSxDQUFDLFFBQVEsQ0FBQyx5Q0FBeUMsQ0FBQztJQUNyRSxJQUFJLEVBQUUsQ0FBQyxDQUFDLE1BQU0sRUFBRSxDQUFDLFFBQVEsQ0FBQyxtQ0FBbUMsQ0FBQztDQUMvRCxDQUFDLENBQUM7QUFLSDs7Ozs7R0FLRztBQUNILE1BQU0sQ0FBQyxNQUFNLHNCQUFzQixHQUFHLENBQUMsQ0FBQyxNQUFNLENBQUM7SUFDN0MsRUFBRSxFQUFFLENBQUMsQ0FBQyxPQUFPLEVBQUUsQ0FBQyxRQUFRLENBQUMsMkRBQTJELENBQUM7SUFDckYsVUFBVSxFQUFFLENBQUMsQ0FBQyxNQUFNLEVBQUUsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxRQUFRLENBQUMscURBQXFELENBQUM7Q0FDbEcsQ0FBQyxDQUFDO0FBS0gsdUZBQXVGO0FBQ3ZGLE1BQU0sQ0FBQyxNQUFNLGdCQUFnQixHQUFHLENBQUMsQ0FBQyxNQUFNLENBQUM7SUFDdkMsYUFBYSxFQUFFLENBQUMsQ0FBQyxPQUFPLEVBQUUsQ0FBQyxRQUFRLENBQUMsZ0RBQWdELENBQUM7SUFDckYsS0FBSyxFQUFFLENBQUMsQ0FBQyxNQUFNLEVBQUUsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxRQUFRLENBQUMsZ0RBQWdELENBQUM7SUFDdkYsT0FBTyxFQUFFLENBQUM7U0FDUCxPQUFPLEVBQUU7U0FDVCxRQUFRLENBQUMsOEVBQThFLENBQUM7Q0FDNUYsQ0FBQyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBXaXJlLWZvcm1hdCBjb250cmFjdCBmb3IgdGhlIGVtYWlsIG9uZS10aW1lLXBhc3N3b3JkIEFDQ0VTUyBHQVRFLlxuICpcbiAqIEEgY29tcGFuaW9uIHRvIHRoZSBlbWFpbCBhZGQtb24ncyBzZW5kIGNvbnRyYWN0ICh7QGxpbmsgLi9lbWFpbH0pOiB3aGVyZSB0aGF0XG4gKiBsZXRzIGFuIGFnZW50IHNlbmQgbWFpbCwgdGhpcyBsZXRzIGFuIEFwcEtpdCBhcHAgcHV0IGFuIGVtYWlsLU9UUCBnYXRlIGluIGZyb250XG4gKiBvZiBpdHNlbGYgLSB0aGUgbG9naW4gZmxvdyBmb3IgYW4gYXBwIGV4cG9zZWQgcHVibGljbHkgKGUuZy4gdGhyb3VnaCBhIHBvcnRyXG4gKiB0dW5uZWwgdGhhdCBieXBhc3NlcyB0aGUgRGF0YWJyaWNrcyBmcm9udCBkb29yKS4gUHVyZSB6b2Qgc28gdGhlIHNlcnZlciByb3V0ZXMsXG4gKiB0aGUgUmVhY3QgYEF1dGhHYXRlYCwgYW5kIGFueSBjbGllbnQgdmFsaWRhdGUgYWdhaW5zdCBvbmUgZGVmaW5pdGlvbi5cbiAqXG4gKiBGbG93OiBgUE9TVCAvcmVxdWVzdGAgKGVtYWlsKSAtPiBhIDYtZGlnaXQgY29kZSBpcyBlbWFpbGVkIC0+IGBQT1NUIC92ZXJpZnlgXG4gKiAoZW1haWwgKyBjb2RlKSAtPiBhbiBIdHRwT25seSBzZXNzaW9uIGNvb2tpZSBpcyBzZXQgLT4gYEdFVCAvc3RhdHVzYCByZXBvcnRzXG4gKiB3aGV0aGVyIHRoZSBjYWxsZXIgaXMgYXV0aGVudGljYXRlZC4gYHJlcXVlc3RgIEFMV0FZUyByZXBvcnRzIHN1Y2Nlc3MgKHRoZVxuICogc2VydmVyIG5ldmVyIHJldmVhbHMgd2hldGhlciBhbiBhZGRyZXNzIGlzIGFsbG93LWxpc3RlZCBvciB3YXMgYWN0dWFsbHkgc2VudCBhXG4gKiBjb2RlIC0gYW50aS1lbnVtZXJhdGlvbikuXG4gKlxuICogQG1vZHVsZVxuICovXG5cbmltcG9ydCB7IHogfSBmcm9tIFwiem9kXCI7XG5cbi8qKiBgUE9TVCAvYXBpL2VtYWlsL2F1dGgvcmVxdWVzdGAgYm9keTogYXNrIGZvciBhIGNvZGUgdG8gYmUgZW1haWxlZC4gKi9cbmV4cG9ydCBjb25zdCBhdXRoUmVxdWVzdFNjaGVtYSA9IHoub2JqZWN0KHtcbiAgZW1haWw6IHouc3RyaW5nKCkuZGVzY3JpYmUoXCJBZGRyZXNzIHRvIGVtYWlsIGEgb25lLXRpbWUgY29kZSB0bywgaWYgaXQgaXMgYWxsb3dlZC5cIiksXG59KTtcblxuLyoqIHtAbGluayBhdXRoUmVxdWVzdFNjaGVtYX0gKi9cbmV4cG9ydCB0eXBlIEF1dGhSZXF1ZXN0ID0gei5pbmZlcjx0eXBlb2YgYXV0aFJlcXVlc3RTY2hlbWE+O1xuXG4vKipcbiAqIGBQT1NUIC9hcGkvZW1haWwvYXV0aC9yZXF1ZXN0YCByZXNwb25zZS4gQWx3YXlzIGB7IG9rOiB0cnVlIH1gIG9uIGFcbiAqIHdlbGwtZm9ybWVkIHJlcXVlc3QsIHJlZ2FyZGxlc3Mgb2Ygd2hldGhlciB0aGUgYWRkcmVzcyB3YXMgYWxsb3dlZCBvciBhIGNvZGVcbiAqIHdhcyBhY3R1YWxseSBzZW50IC0gdGhlIGNsaWVudCBjYW5ub3QgZGlzdGluZ3Vpc2ggYW4gYWxsb3dlZCBhZGRyZXNzIGZyb20gYVxuICogcmVqZWN0ZWQgb25lIChhbnRpLWVudW1lcmF0aW9uKS4gYHJldHJ5QWZ0ZXJgIGlzIHNldCBvbmx5IHdoZW4gdGhlIGNhbGxlciBpc1xuICogcmF0ZS1saW1pdGVkLCBzbyBhIFVJIGNhbiBzaG93IGEgY29vbGRvd24gd2l0aG91dCBsZWFraW5nIGFsbG93LWxpc3Qgc3RhdGUuXG4gKi9cbmV4cG9ydCBjb25zdCBhdXRoUmVxdWVzdFJlc3VsdFNjaGVtYSA9IHoub2JqZWN0KHtcbiAgb2s6IHoubGl0ZXJhbCh0cnVlKS5kZXNjcmliZShcIkFsd2F5cyB0cnVlIGZvciBhIHdlbGwtZm9ybWVkIHJlcXVlc3QgKGFudGktZW51bWVyYXRpb24pLlwiKSxcbiAgcmV0cnlBZnRlcjogelxuICAgIC5udW1iZXIoKVxuICAgIC5vcHRpb25hbCgpXG4gICAgLmRlc2NyaWJlKFwiU2Vjb25kcyB0byB3YWl0IGJlZm9yZSByZXF1ZXN0aW5nIGFnYWluLCB3aGVuIHJhdGUtbGltaXRlZC5cIiksXG59KTtcblxuLyoqIHtAbGluayBhdXRoUmVxdWVzdFJlc3VsdFNjaGVtYX0gKi9cbmV4cG9ydCB0eXBlIEF1dGhSZXF1ZXN0UmVzdWx0ID0gei5pbmZlcjx0eXBlb2YgYXV0aFJlcXVlc3RSZXN1bHRTY2hlbWE+O1xuXG4vKiogYFBPU1QgL2FwaS9lbWFpbC9hdXRoL3ZlcmlmeWAgYm9keTogc3VibWl0IHRoZSBlbWFpbGVkIGNvZGUuICovXG5leHBvcnQgY29uc3QgYXV0aFZlcmlmeVNjaGVtYSA9IHoub2JqZWN0KHtcbiAgZW1haWw6IHouc3RyaW5nKCkuZGVzY3JpYmUoXCJUaGUgYWRkcmVzcyB0aGUgY29kZSB3YXMgcmVxdWVzdGVkIGZvci5cIiksXG4gIGNvZGU6IHouc3RyaW5nKCkuZGVzY3JpYmUoXCJUaGUgb25lLXRpbWUgY29kZSBmcm9tIHRoZSBlbWFpbC5cIiksXG59KTtcblxuLyoqIHtAbGluayBhdXRoVmVyaWZ5U2NoZW1hfSAqL1xuZXhwb3J0IHR5cGUgQXV0aFZlcmlmeSA9IHouaW5mZXI8dHlwZW9mIGF1dGhWZXJpZnlTY2hlbWE+O1xuXG4vKipcbiAqIGBQT1NUIC9hcGkvZW1haWwvYXV0aC92ZXJpZnlgIHJlc3BvbnNlLiBgb2tgIHRydWUgbWVhbnMgdGhlIGNvZGUgbWF0Y2hlZCBhbmRcbiAqIGFuIEh0dHBPbmx5IHNlc3Npb24gY29va2llIHdhcyBzZXQ7IGZhbHNlIG1lYW5zIGl0IGRpZCBub3QgKHdyb25nLCBleHBpcmVkLCBvclxuICogdG9vIG1hbnkgYXR0ZW1wdHMpIC0gdGhlIG1lc3NhZ2UgaXMgZGVsaWJlcmF0ZWx5IGdlbmVyaWMuIGByZXRyeUFmdGVyYCBpcyBzZXRcbiAqIHdoZW4gdGhlIGZhaWx1cmUgd2FzIGEgcmF0ZSBsaW1pdC5cbiAqL1xuZXhwb3J0IGNvbnN0IGF1dGhWZXJpZnlSZXN1bHRTY2hlbWEgPSB6Lm9iamVjdCh7XG4gIG9rOiB6LmJvb2xlYW4oKS5kZXNjcmliZShcIlRydWUgd2hlbiB0aGUgY29kZSBtYXRjaGVkIGFuZCBhIHNlc3Npb24gd2FzIGVzdGFibGlzaGVkLlwiKSxcbiAgcmV0cnlBZnRlcjogei5udW1iZXIoKS5vcHRpb25hbCgpLmRlc2NyaWJlKFwiU2Vjb25kcyB0byB3YWl0IGJlZm9yZSByZXRyeWluZywgd2hlbiByYXRlLWxpbWl0ZWQuXCIpLFxufSk7XG5cbi8qKiB7QGxpbmsgYXV0aFZlcmlmeVJlc3VsdFNjaGVtYX0gKi9cbmV4cG9ydCB0eXBlIEF1dGhWZXJpZnlSZXN1bHQgPSB6LmluZmVyPHR5cGVvZiBhdXRoVmVyaWZ5UmVzdWx0U2NoZW1hPjtcblxuLyoqIGBHRVQgL2FwaS9lbWFpbC9hdXRoL3N0YXR1c2AgcmVzcG9uc2U6IGlzIHRoZSBjYWxsZXIgYXV0aGVudGljYXRlZCwgYW5kIGFzIHdob20uICovXG5leHBvcnQgY29uc3QgYXV0aFN0YXR1c1NjaGVtYSA9IHoub2JqZWN0KHtcbiAgYXV0aGVudGljYXRlZDogei5ib29sZWFuKCkuZGVzY3JpYmUoXCJUcnVlIHdoZW4gdGhlIHJlcXVlc3QgY2FycmllcyBhIHZhbGlkIHNlc3Npb24uXCIpLFxuICBlbWFpbDogei5zdHJpbmcoKS5vcHRpb25hbCgpLmRlc2NyaWJlKFwiVGhlIGF1dGhlbnRpY2F0ZWQgYWRkcmVzcywgd2hlbiBhdXRoZW50aWNhdGVkLlwiKSxcbiAgZW5hYmxlZDogelxuICAgIC5ib29sZWFuKClcbiAgICAuZGVzY3JpYmUoXCJUcnVlIHdoZW4gdGhlIGdhdGUgaXMgYWN0aXZlOyBmYWxzZSBtZWFucyB0aGUgYXBwIGlzIG9wZW4gKG5vIGxvZ2luIG5lZWRlZCkuXCIpLFxufSk7XG5cbi8qKiB7QGxpbmsgYXV0aFN0YXR1c1NjaGVtYX0gKi9cbmV4cG9ydCB0eXBlIEF1dGhTdGF0dXMgPSB6LmluZmVyPHR5cGVvZiBhdXRoU3RhdHVzU2NoZW1hPjtcbiJdfQ==

package/lib/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/email.ts","../index.ts"],"version":"5.9.3"}
+{"root":["../src/auth.ts","../src/email.ts","../index.ts"],"version":"5.9.3"}

package/package.json

@@ -5,28 +5,46 @@
     "url": "git+https://github.com/reggie-db/dbx-tools.git",
     "directory": "packages/shared/email"
   },
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "prepack": "projen prepack",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  },
   "devDependencies": {
+    "@types/bun": "^1.3.14",
     "@types/node": "^24.6.0",
-    "tsx": "^4.23.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "zod": "4.3.6",
-    "@dbx-tools/shared-core": "0.6.40"
+    "@dbx-tools/shared-core": "0.6.42",
+    "zod": "4.3.6"
   },
-  "main": "./lib/index.js",
+  "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "main": "./lib/index.js",
+    "types": "./lib/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "./package.json": "./package.json"
+    }
   },
-  "version": "0.6.40",
-  "types": "./lib/index.d.ts",
+  "version": "0.6.42",
+  "types": "index.ts",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
-    },
+    ".": "./index.ts",
     "./package.json": "./package.json"
   },
   "files": [
@@ -39,16 +57,5 @@
       "shared"
     ]
   },
-  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
-  "scripts": {
-    "build": "projen build",
-    "compile": "projen compile",
-    "default": "projen default",
-    "package": "projen package",
-    "post-compile": "projen post-compile",
-    "pre-compile": "projen pre-compile",
-    "test": "projen test",
-    "watch": "projen watch",
-    "projen": "projen"
-  }
-}
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"bunx projen\"."
+}

package/src/auth.ts

@@ -0,0 +1,80 @@
+/**
+ * Wire-format contract for the email one-time-password ACCESS GATE.
+ *
+ * A companion to the email add-on's send contract ({@link ./email}): where that
+ * lets an agent send mail, this lets an AppKit app put an email-OTP gate in front
+ * of itself - the login flow for an app exposed publicly (e.g. through a portr
+ * tunnel that bypasses the Databricks front door). Pure zod so the server routes,
+ * the React `AuthGate`, and any client validate against one definition.
+ *
+ * Flow: `POST /request` (email) -> a 6-digit code is emailed -> `POST /verify`
+ * (email + code) -> an HttpOnly session cookie is set -> `GET /status` reports
+ * whether the caller is authenticated. `request` ALWAYS reports success (the
+ * server never reveals whether an address is allow-listed or was actually sent a
+ * code - anti-enumeration).
+ *
+ * @module
+ */
+
+import { z } from "zod";
+
+/** `POST /api/email/auth/request` body: ask for a code to be emailed. */
+export const authRequestSchema = z.object({
+  email: z.string().describe("Address to email a one-time code to, if it is allowed."),
+});
+
+/** {@link authRequestSchema} */
+export type AuthRequest = z.infer<typeof authRequestSchema>;
+
+/**
+ * `POST /api/email/auth/request` response. Always `{ ok: true }` on a
+ * well-formed request, regardless of whether the address was allowed or a code
+ * was actually sent - the client cannot distinguish an allowed address from a
+ * rejected one (anti-enumeration). `retryAfter` is set only when the caller is
+ * rate-limited, so a UI can show a cooldown without leaking allow-list state.
+ */
+export const authRequestResultSchema = z.object({
+  ok: z.literal(true).describe("Always true for a well-formed request (anti-enumeration)."),
+  retryAfter: z
+    .number()
+    .optional()
+    .describe("Seconds to wait before requesting again, when rate-limited."),
+});
+
+/** {@link authRequestResultSchema} */
+export type AuthRequestResult = z.infer<typeof authRequestResultSchema>;
+
+/** `POST /api/email/auth/verify` body: submit the emailed code. */
+export const authVerifySchema = z.object({
+  email: z.string().describe("The address the code was requested for."),
+  code: z.string().describe("The one-time code from the email."),
+});
+
+/** {@link authVerifySchema} */
+export type AuthVerify = z.infer<typeof authVerifySchema>;
+
+/**
+ * `POST /api/email/auth/verify` response. `ok` true means the code matched and
+ * an HttpOnly session cookie was set; false means it did not (wrong, expired, or
+ * too many attempts) - the message is deliberately generic. `retryAfter` is set
+ * when the failure was a rate limit.
+ */
+export const authVerifyResultSchema = z.object({
+  ok: z.boolean().describe("True when the code matched and a session was established."),
+  retryAfter: z.number().optional().describe("Seconds to wait before retrying, when rate-limited."),
+});
+
+/** {@link authVerifyResultSchema} */
+export type AuthVerifyResult = z.infer<typeof authVerifyResultSchema>;
+
+/** `GET /api/email/auth/status` response: is the caller authenticated, and as whom. */
+export const authStatusSchema = z.object({
+  authenticated: z.boolean().describe("True when the request carries a valid session."),
+  email: z.string().optional().describe("The authenticated address, when authenticated."),
+  enabled: z
+    .boolean()
+    .describe("True when the gate is active; false means the app is open (no login needed)."),
+});
+
+/** {@link authStatusSchema} */
+export type AuthStatus = z.infer<typeof authStatusSchema>;