@volter/twin-xidentity 0.1.0 → 0.1.2

package/dist/src/xidentity-consent-ui.d.ts

@@ -1,4 +1,4 @@
-import { type ConsentView, type ErrorPageProps } from '../client/xidentity-consent.js';
+import { type ConsentScopeRow, type ConsentView, type ErrorPageProps } from '../client/xidentity-consent.js';
 export type { ConsentAccount, ConsentScopeRow, ConsentView, ErrorPageProps } from '../client/xidentity-consent.js';
 export { XIDENTITY_CONSENT_CLIENT_CSS as CONSENT_CLIENT_CSS, XIDENTITY_CONSENT_CLIENT_JS as CONSENT_CLIENT_JS } from './xidentity-consent-client.gen.js';
 /** Twin-only asset paths, clearly namespaced so they can never be mistaken for vendor surface. */
@@ -15,7 +15,31 @@ export declare function xIdentityConsentState(opts: {
     requestId: string;
     origin: string;
 }): ConsentView | null;
+/**
+ * What an OAuth 1.0a token lets an app do, as X's authorize screen lists it. OAuth 1.0a has no
+ * scopes: the App's permission level (Read / Read and write) decides the grant (docs.x.com
+ * developer-apps, "App permissions (OAuth 1.0a)"), and the screen lists what that level allows.
+ * The lines follow X's OAuth 1.0a authorize page as widely screenshotted; the live wording was not
+ * captured (`xidentity.oauth1.consent_wording`, todo). Keyed rows, so a row is never invented
+ * outside the two documented levels.
+ */
+export declare const OAUTH1_CONSENT_ROWS: Record<'read' | 'write', ConsentScopeRow[]>;
+/**
+ * THE OAUTH 1.0a STATE BUILDER — the authorize screen for a pending request token, folded out of
+ * the projection: the App's name (`appName`, resolved by the caller from the registered App or the
+ * World's own), the account the request was bound to when the screen was first served, the rows
+ * the granted permission level allows, and the callback's host. `null` for an unknown or settled
+ * request token or a missing account; it invents nothing.
+ */
+export declare function xIdentityOAuth1ConsentState(opts: {
+    root?: string;
+    requestToken: string;
+    appName: string;
+    origin: string;
+}): ConsentView | null;
 /** Render the authorize page from a view model. The tab title mirrors X's "Authorize <app>". */
 export declare function consentPageHtml(view: ConsentView, base?: string): string;
+/** Render the out-of-band PIN page an `oob` request token ends on. */
+export declare function pinPageHtml(appName: string, pin: string, base?: string): string;
 /** Render the authorize-endpoint error page (an un-redirectable failure). */
 export declare function errorPageHtml(props: ErrorPageProps, base?: string): string;

package/dist/src/xidentity-consent-ui.js

@@ -18,7 +18,7 @@
 //     progressive enhancement only, and the serve path never builds (runtime contract R12b, R9).
 import { createElement } from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
-import { ConsentPage, ErrorPage, } from "../client/xidentity-consent.js";
+import { ConsentPage, ErrorPage, PinPage, } from "../client/xidentity-consent.js";
 import { describeScopes, parseScopeParam, sortScopesForConsent } from "./xidentity-scopes.js";
 import { readOne } from "./xidentity-store.js";
 export { XIDENTITY_CONSENT_CLIENT_CSS as CONSENT_CLIENT_CSS, XIDENTITY_CONSENT_CLIENT_JS as CONSENT_CLIENT_JS } from "./xidentity-consent-client.gen.js";
@@ -72,6 +72,63 @@ export function xIdentityConsentState(opts) {
         redirectHost,
     };
 }
+/**
+ * What an OAuth 1.0a token lets an app do, as X's authorize screen lists it. OAuth 1.0a has no
+ * scopes: the App's permission level (Read / Read and write) decides the grant (docs.x.com
+ * developer-apps, "App permissions (OAuth 1.0a)"), and the screen lists what that level allows.
+ * The lines follow X's OAuth 1.0a authorize page as widely screenshotted; the live wording was not
+ * captured (`xidentity.oauth1.consent_wording`, todo). Keyed rows, so a row is never invented
+ * outside the two documented levels.
+ */
+export const OAUTH1_CONSENT_ROWS = {
+    read: [
+        { scope: 'oauth1:timeline', label: 'Posts from your timeline (including protected Posts) as well as your Lists and collections.', group: 'view', known: true },
+        { scope: 'oauth1:profile', label: 'Your X profile information and account settings.', group: 'view', known: true },
+        { scope: 'oauth1:graph', label: 'Accounts you follow, mute, and block.', group: 'view', known: true },
+    ],
+    write: [
+        { scope: 'oauth1:follow', label: 'Follow and unfollow accounts for you.', group: 'do', known: true },
+        { scope: 'oauth1:settings', label: 'Update your profile and account settings for you.', group: 'do', known: true },
+        { scope: 'oauth1:post', label: 'Post and delete Posts for you, and engage with Posts posted by others (Like, un-Like, or reply to a Post, Repost, etc.) for you.', group: 'do', known: true },
+        { scope: 'oauth1:lists', label: 'Create, manage, and delete Lists and collections for you.', group: 'do', known: true },
+        { scope: 'oauth1:moderate', label: 'Mute, block, and report accounts for you.', group: 'do', known: true },
+    ],
+};
+/**
+ * THE OAUTH 1.0a STATE BUILDER — the authorize screen for a pending request token, folded out of
+ * the projection: the App's name (`appName`, resolved by the caller from the registered App or the
+ * World's own), the account the request was bound to when the screen was first served, the rows
+ * the granted permission level allows, and the callback's host. `null` for an unknown or settled
+ * request token or a missing account; it invents nothing.
+ */
+export function xIdentityOAuth1ConsentState(opts) {
+    const row = readOne(opts.root, 'oauth1_request_token', opts.requestToken);
+    if (!row || row.state !== 'pending')
+        return null;
+    const account = readOne(opts.root, 'account', String(row.accountId ?? ''));
+    if (!account)
+        return null;
+    const level = row.accessLevel === 'read' ? 'read' : 'write';
+    const scopes = level === 'read' ? OAUTH1_CONSENT_ROWS.read : [...OAUTH1_CONSENT_ROWS.read, ...OAUTH1_CONSENT_ROWS.write];
+    let redirectHost = '';
+    if (row.callback !== 'oob') {
+        try {
+            redirectHost = new URL(String(row.callback)).host;
+        }
+        catch {
+            redirectHost = String(row.callback);
+        }
+    }
+    return {
+        requestId: opts.requestToken,
+        origin: opts.origin,
+        app: { clientId: String(row.consumerKey), name: opts.appName },
+        account: toConsentAccount(account),
+        scopes,
+        redirectHost,
+        decisionPath: '/oauth/authorize',
+    };
+}
 /** `base` is where the twin is reached (`twinPublicBase`: origin plus any served-World mount path),
  *  so the page's assets resolve inside the World's mount; empty for an in-process render. */
 function page(title, bodyMarkup, base) {
@@ -88,6 +145,10 @@ export function consentPageHtml(view, base = '') {
     const markup = renderToStaticMarkup(createElement(ConsentPage, { view }));
     return page(`Authorize ${view.app.name} to access your account? / X`, markup, base);
 }
+/** Render the out-of-band PIN page an `oob` request token ends on. */
+export function pinPageHtml(appName, pin, base = '') {
+    return page(`${appName} / X`, renderToStaticMarkup(createElement(PinPage, { appName, pin })), base);
+}
 /** Render the authorize-endpoint error page (an un-redirectable failure). */
 export function errorPageHtml(props, base = '') {
     return page(`Error ${props.status}: ${props.code} / X`, renderToStaticMarkup(createElement(ErrorPage, props)), base);

package/dist/src/xidentity-oauth1.d.ts

@@ -0,0 +1,93 @@
+import { type TwinResource } from '@volter/world-core';
+import { type XResponse } from './xidentity-problems.js';
+import { type Row } from './xidentity-store.js';
+/** RFC 3986 percent-encoding, the guide's "Percent encoding parameters" (unreserved: A-Z a-z 0-9 - . _ ~). */
+export declare const pct: (s: string) => string;
+/** The `Authorization: OAuth k="v", …` header as decoded pairs; null when it is not an OAuth header. */
+export declare function parseOAuthHeader(value: string | undefined): Array<[string, string]> | null;
+export type SignedRequest = {
+    method: string;
+    /** The URL the client signed, without its query: scheme://host[:non-default port]/path. */
+    baseUrl: string;
+    /** Header pairs (realm excluded later), query pairs and — for a form-encoded body — body pairs. */
+    header: Array<[string, string]>;
+    query: Array<[string, string]>;
+    body: Array<[string, string]>;
+};
+/** Every oauth_* protocol parameter the request carries, header first (RFC 5849 §3.5 order). */
+export declare function oauth1Params(req: SignedRequest): Map<string, string>;
+/** HMAC-SHA1 over the base string with `pct(consumer_secret)&pct(token_secret)` — the guide's key. */
+export declare function signatureMatches(req: SignedRequest, consumerSecret: string, tokenSecret: string): boolean;
+/**
+ * The URL the client signed. Reached through the injector the request still names X's host (the
+ * Node path keeps Host; the fetch path names it in `x-volter-twin-original-host`) and the client
+ * signed `https://<that host><path>`. Reached directly, it signed where it sent: `origin` (the
+ * twin's public base, a World mount included). A direct in-process call with neither is X's own
+ * API origin.
+ */
+export declare function signedBaseUrl(headers: Record<string, string> | undefined, origin: string | undefined, path: string): string;
+/** Split a request into the signed pieces. Body pairs count only for a form-encoded body (the guide). */
+export declare function signedRequestOf(req: {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string>;
+    origin?: string;
+}): SignedRequest;
+/** 215 "Bad Authentication data." — no usable OAuth header at all; X's table pairs it with HTTP 400. */
+export declare const badAuthenticationData: () => XResponse;
+/** 32 "Could not authenticate you." — an unknown consumer key or a signature that does not verify (401). */
+export declare const couldNotAuthenticate: () => XResponse;
+/** 89 "Invalid or expired token." — verbatim from the invalidate_token example (api-reference). */
+export declare const invalidOrExpiredToken: () => XResponse;
+/** 415, the body verbatim from developer-apps' troubleshooting. HTTP 403 is EXTRAPOLATION
+ *  (the page shows the body only) — `xidentity.oauth1.callback_refusal_status` pins it. */
+export declare const callbackNotApproved: () => XResponse;
+export type OAuth1App = {
+    consumerKey: string;
+    secret: string;
+    name: string;
+    callbackUrls: string[];
+    accessLevel: 'read' | 'read-write';
+    world?: true;
+};
+/** The env pairs a World names its X App with: Postiz's X_API_KEY / X_API_SECRET (x.provider.ts),
+ *  and the TWITTER_ spelling of the same "API Key and Secret" (docs.x.com's own name for the pair). */
+export declare const WORLD_APP_ENV: ReadonlyArray<readonly [string, string]>;
+/**
+ * The World's own App: the one its env describes. An app holding consumer keys is an App its
+ * developer made in the X developer console, so the twin takes the World's values as that App's —
+ * the slack pack's worldSlackApp precedent. Only a value the World sets counts (worldEnvValue),
+ * never one the caller's shell passes. Where the documentation stops and the twin decides: the App
+ * is named for the World (VOLTER_WORLD_NAME, else "World app"); a key with no secret is no App;
+ * its console lists no callback URLs, since the env names none, so it accepts the callback each
+ * request names; its permission is Read and write, which an `x_auth_access_type=read` narrows.
+ */
+export declare function worldOAuth1App(): OAuth1App | undefined;
+/** The App a consumer key names: one registered through the twin door, else the World's own. */
+export declare function oauth1AppOf(resources: readonly TwinResource[], consumerKey: string | undefined): OAuth1App | undefined;
+type Req = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string>;
+    root?: string;
+    occurredAt?: string;
+    origin?: string;
+    readOnly?: boolean;
+};
+export type OAuth1Principal = {
+    token: Row;
+    app: OAuth1App;
+};
+/** A request signed with an access token this pack issued and has not revoked; null otherwise. */
+export declare function verifyUserContext(req: Req, resources: readonly TwinResource[]): OAuth1Principal | null;
+/** The OAuth 2.0 scopes an OAuth 1.0a token's permission level stands for on a v2 endpoint that
+ *  declares both schemes (the OpenAPI's `security` lists OAuth2UserToken scopes OR UserToken). */
+export declare function scopesOfAccessLevel(level: unknown): string[];
+export declare const OAUTH1_ENDPOINTS: readonly ["POST /oauth/request_token", "GET /oauth/authorize", "POST /oauth/authorize", "GET /oauth/authenticate", "POST /oauth/access_token", "POST /1.1/oauth/invalidate_token", "POST /1.1/oauth/invalidate_token.json"];
+/** Paths this slice writes on (read-only twins refuse them). */
+export declare const OAUTH1_WRITE_PATHS: Set<string>;
+/** Route an OAuth 1.0a request; null when the path is not this slice's. */
+export declare function routeOAuth1(req: Req, method: string, path: string): Promise<XResponse | null>;
+export {};