@333eco/heartbank-api 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @333eco/heartbank-api
 
-The typed client for every HeartBank® API: **Log in with HeartBank®**, **Sign with HeartBank®**, **Thank with HeartBank®**, **Lookup** and **Verify**. Generated from the APIs' own OpenAPI descriptions, so it cannot drift from them.
+The typed client for every HeartBank® API: **Log in with HeartBank®**, **Sign with HeartBank®**, **Confirm with HeartBank®**, **Thank with HeartBank®**, **Lookup** and **Verify**. Generated from the APIs' own OpenAPI descriptions, so it cannot drift from them.
 
 ```sh
 npm install @333eco/heartbank-api
@@ -44,6 +44,26 @@ if ("ticket" in ticket) {
 - The browser steps are links the client builds, never calls: `LoginClient#authorizeUrl`, `LoginClient#logOutUrl`, `SignClient#signPageUrl`.
 - Any answer outside 2xx throws an `ApiError` with the service's own `error` and `why`.
 
+## A human in the loop: Confirm with HeartBank®
+
+A person's own passkey press for one action your app names, so you know a person, not a script, did it. They must have logged in to your app with Log in with HeartBank®; `sub` is your app's own ID for them.
+
+```js
+import { ConfirmClient } from "@333eco/heartbank-api";
+
+const confirm = new ConfirmClient({ assertion: async (aud) => signClientAssertion(aud) });
+
+// 1. On upload: your server asks. `hash` is the file's SHA-256, `return_to` one of your registered redirect URLs.
+const { ticket, url } = await confirm.request({ body: { sub, kind: "upload", hash, return_to: "https://yourapp.example/cb" } });
+// 2. Send the person's browser there, with the ticket in the FRAGMENT:
+const go = `${url}#${new URLSearchParams({ ticket, state })}`;
+// 3. They come back with #confirm=<result>&state=… (or #declined=1&state=…). Your server redeems it, once:
+const done = await confirm.redeem({ body: { result } });
+if (done.sub !== sub || done.hash !== hash) throw new Error("not this person, or not this file");
+```
+
+It proves presence, not personhood: never call a confirmed person "verified". For a file someone puts their name to, in public and for good, use Sign with HeartBank®.
+
 ## Docs
 
 The full docs open at developers.333.eco. Until then, this README and the types are the docs; every method links the page it will live on.

package/dist/confirm.d.ts

@@ -0,0 +1,43 @@
+import { type ClientOptions } from "./runtime.js";
+export type ErrorBody = {
+    error: string;
+    why?: string;
+};
+export type Ticket = {
+    /** Opaque to your app; put it in the page's address fragment, never a query. */ ticket: string;
+    /** https://sign.333.eco/confirm */ url: string;
+    /** Seconds the ticket lasts (600). */ expires_in: number;
+};
+export type Confirmed = {
+    confirmed: true;
+    /** Your app's own sub for the person who pressed: check it is the person you asked about. */ sub: string;
+    kind: "upload";
+    /** The SHA-256 you asked about: check it is the file you hold. */ hash?: string;
+    /** When they pressed (seconds since 1970). */ at: number;
+};
+/** Confirm with HeartBank®: A person's own passkey press for one action your app names: a human in the loop, so you know a person, not a script, did it. */
+export declare class ConfirmClient {
+    private readonly o;
+    constructor(o?: ClientOptions);
+    /** Step 1: ask a person to confirm one action. @see https://developers.333.eco/confirm#request */
+    request(input: {
+        body: Omit<{
+            client_assertion_type: string;
+            client_assertion: string;
+            /** Your app's own sub for the person, from their Log in with HeartBank® ID token. */ sub: string;
+            /** What they are confirming, from a closed list: the page says it in its own words. */ kind: "upload";
+            /** Optional: the SHA-256 of the thing (a file being uploaded), 64 lowercase hex. The page shows its first eight. */ hash?: string;
+            /** One of your app's registered redirect URLs. */ return_to: string;
+        }, "client_assertion_type" | "client_assertion">;
+    }): Promise<Ticket>;
+    /** Step 2: the page where the person presses. @see https://developers.333.eco/confirm#page */
+    pageUrl(): string;
+    /** Step 3: redeem the result, once. @see https://developers.333.eco/confirm#redeem */
+    redeem(input: {
+        body: Omit<{
+            client_assertion_type: string;
+            client_assertion: string;
+            /** The `confirm` value the browser brought back. */ result: string;
+        }, "client_assertion_type" | "client_assertion">;
+    }): Promise<Confirmed>;
+}

package/dist/confirm.js

@@ -0,0 +1,45 @@
+// Generated by scripts/gen-client.mjs from openapi/confirm.json. ⛔ Do not edit: change the description and run npm run client.
+import { send, urlOf } from "./runtime.js";
+/** Confirm with HeartBank®: A person's own passkey press for one action your app names: a human in the loop, so you know a person, not a script, did it. */
+export class ConfirmClient {
+    o;
+    constructor(o = {}) {
+        this.o = o;
+    }
+    /** Step 1: ask a person to confirm one action. @see https://developers.333.eco/confirm#request */
+    request(input) {
+        return send(this.o, {
+            method: "POST",
+            base: "https://login.333.eco",
+            path: "/confirm/request",
+            pathParams: undefined,
+            query: undefined,
+            headers: undefined,
+            body: input.body,
+            contentType: "application/x-www-form-urlencoded",
+            security: "privateKeyJwt",
+            audience: "endpoint",
+            accept: "json",
+        });
+    }
+    /** Step 2: the page where the person presses. @see https://developers.333.eco/confirm#page */
+    pageUrl() {
+        return urlOf(this.o.baseUrl ?? "https://sign.333.eco", "/confirm", undefined, undefined);
+    }
+    /** Step 3: redeem the result, once. @see https://developers.333.eco/confirm#redeem */
+    redeem(input) {
+        return send(this.o, {
+            method: "POST",
+            base: "https://login.333.eco",
+            path: "/confirm/redeem",
+            pathParams: undefined,
+            query: undefined,
+            headers: undefined,
+            body: input.body,
+            contentType: "application/x-www-form-urlencoded",
+            security: "privateKeyJwt",
+            audience: "endpoint",
+            accept: "json",
+        });
+    }
+}

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { LoginClient } from "./login.js";
 export * as login from "./login.js";
 export { SignClient } from "./sign.js";
 export * as sign from "./sign.js";
+export { ConfirmClient } from "./confirm.js";
+export * as confirm from "./confirm.js";
 export { ThankClient } from "./thank.js";
 export * as thank from "./thank.js";
 export { LookupClient } from "./lookup.js";

package/dist/index.js

@@ -4,6 +4,8 @@ export { LoginClient } from "./login.js";
 export * as login from "./login.js";
 export { SignClient } from "./sign.js";
 export * as sign from "./sign.js";
+export { ConfirmClient } from "./confirm.js";
+export * as confirm from "./confirm.js";
 export { ThankClient } from "./thank.js";
 export * as thank from "./thank.js";
 export { LookupClient } from "./lookup.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@333eco/heartbank-api",
-  "version": "0.1.0",
-  "description": "The typed client for every HeartBank® API (Log in, Sign and Thank with HeartBank®, and Verify), generated from developers.333.eco's OpenAPI descriptions. For your server: it never holds a key.",
+  "version": "0.2.0",
+  "description": "The typed client for every HeartBank® API (Log in, Sign, Confirm and Thank with HeartBank®, Lookup and Verify), generated from developers.333.eco's OpenAPI descriptions. For your server: it never holds a key.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",