@c9up/transit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# @c9up/transit
+
+> Federated sign-in for the Ream framework — everything that lets a person
+> prove who they are through an authority your application does not own.
+
+Today: SAML 2.0, LDAP, generic OpenID Connect, OAuth1, OAuth2, and the
+providers that speak them — written here, without a dependency, down to the XML
+reader a signature is canonicalized over and the BER a directory is asked in.
+
+Part of **[Ream](https://github.com/C9up/ream)**. Independent, publishable
+package — it imports nothing from the rest of the framework.
+
+## Installation
+
+```bash
+pnpm add @c9up/transit
+```
+
+```ts
+// reamrc.ts
+providers: [
+  () => import('@c9up/transit/provider'),
+]
+```
+
+`ream add @c9up/transit` installs it, registers the provider and writes
+`config/transit.ts`. The rest of this page assumes that has run.
+
+## Configuration
+
+```ts
+// config/transit.ts
+import { defineConfig, socials } from '@c9up/transit'
+
+export default defineConfig({
+  google: socials.google({
+    clientId: env.get('GOOGLE_CLIENT_ID'),
+    clientSecret: env.get('GOOGLE_CLIENT_SECRET'),
+    callbackUrl: 'https://acme.test/auth/google/callback',
+  }),
+})
+```
+
+The keys are yours: two entries may reach the same provider with different
+credentials, and `use(name)` asks for the key.
+
+## The round trip
+
+```ts
+import transit from '@c9up/transit/services/main'
+
+// Send the user off
+const { url, state, secret } = await transit.begin('google')
+ctx.session.put('transit_state', state)
+ctx.session.put('transit_secret', secret)
+return ctx.response.redirect(url)
+
+// ... and receive them back
+const { user, token } = await transit.callback(
+  'google',
+  ctx.request.input('code'),
+  ctx.request.input('state'),
+  ctx.session.pull('transit_state'),
+  ctx.session.pull('transit_secret'),
+)
+```
+
+`begin()` works for every provider. `secret` is `undefined` for a plain OAuth2
+provider, the PKCE verifier for one that mandates it, and the request-token
+secret for OAuth1 — storing and returning it unconditionally is what lets one
+controller serve all three.
+
+## Providers
+
+`socials.apple`, `.discord`, `.facebook`, `.github`, `.google`, `.linkedin`,
+`.linkedinOpenidConnect`, `.spotify`, `.twitter` (OAuth1), `.twitterX` (OAuth2).
+
+Sign in with Apple takes a key rather than a secret, its callback arrives as a
+POST, and it sends the user's name exactly once — read it with
+`parseAppleUser(ctx.request.input('user'))` and store it.
+
+## LDAP and Active Directory
+
+```ts
+export default defineConfig({
+  staff: ldap({
+    url: 'ldaps://directory.acme.test',
+    baseDn: 'dc=acme,dc=test',
+    loginAttribute: 'uid',
+    bindDn: 'cn=reader,dc=acme,dc=test',
+    bindPassword: env.get('LDAP_PASSWORD'),
+  }),
+})
+
+const user = await transit.authenticate('staff', username, password)
+```
+
+An empty password is refused before a socket is opened: a simple bind with no
+password is an anonymous bind, and the directory answers success. And there is
+no filter string — a filter is a structure whose values are written as octets,
+so a username cannot become syntax.
+
+## SAML 2.0
+
+```ts
+export default defineConfig({
+  corp: saml({
+    entityId: 'https://acme.test/saml',
+    callbackUrl: 'https://acme.test/saml/acs',
+    issuer: 'https://idp.acme.test/metadata',
+    signOnUrl: 'https://idp.acme.test/sso',
+    certificates: [env.get('IDP_CERTIFICATE')],
+    replayStore: replayStores.redis({ connection: 'main' }),
+  }),
+})
+```
+
+The certificates come from the provider's metadata and nowhere else. The
+element the signature covers is the element that is read — nothing is looked up
+in the document afterwards, which is what closes XML Signature Wrapping. An
+assertion is a bearer token, so its id is remembered until it expires.
+
+That record has to be **shared by every replica**, because it is what stops the
+same assertion being presented twice. The in-process default bounds replay
+within one process and not beyond it, so in production the driver refuses to
+choose it for you — say which store you want:
+
+```ts
+replayStore: replayStores.redis({ connection: 'main' })  // shared across replicas
+replayStore: replayStores.memory()                       // a single process, deliberately
+```
+
+Outside production the in-process store remains the default: one dev process is
+the case it is correct for.
+
+## OpenID Connect
+
+One driver for every conforming provider — Keycloak, Auth0, Okta, Entra ID,
+Authentik, Zitadel. Give it an issuer; the endpoints, keys and algorithms come
+from what the provider publishes.
+
+```ts
+export default defineConfig({
+  work: oidc({
+    issuer: 'https://id.acme.com',
+    clientId: env.get('OIDC_CLIENT_ID'),
+    clientSecret: env.get('OIDC_CLIENT_SECRET'),
+    callbackUrl: 'https://acme.test/auth/work/callback',
+  }),
+})
+```
+
+The `id_token` is a signed statement about who the user is, so it is verified
+before anyone is signed in: signature against the published key, algorithm
+taken from what the provider **declared** rather than from the token's own
+header, and every claim that binds it to this exchange — `iss`, `aud`, `exp`,
+and the `nonce`. Only asymmetric signatures are accepted.
+
+## Before linking an account by email
+
+`user.emailVerificationState` is `verified`, `unverified` or `unsupported`.
+Only the first may be trusted to match an existing account: `unverified` means
+anyone able to type that address at the provider now holds it, and
+`unsupported` means the provider says nothing either way.
+
+## Testing
+
+```ts
+import { FakeTransit } from '@c9up/transit/testing'
+
+const transit = new FakeTransit().willReturn('google', { email: 'ada@acme.test' })
+container.singleton(TransitManager, () => transit)
+
+transit.assertSignedIn('google')
+```
+
+The double still enforces the state round trip, the value `begin()` asked you
+to keep, and — for a directory — the refusal of an empty password. A fake that
+let a forgetful controller pass would teach applications to ship one.
+
+## Entry points
+
+- `@c9up/transit` — main API
+- `@c9up/transit/config` — `defineConfig`, `socials`, `oidc`, `saml`, `ldap`
+- `@c9up/transit/provider` — Ream IoC provider
+- `@c9up/transit/services/main` — container service accessor
+- `@c9up/transit/testing` — `FakeTransit`
+
+## License
+
+MIT

package/dist/Oauth1Driver.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The OAuth 1.0a three-legged flow.
+ *
+ * A different protocol from OAuth2, not a variation on it. Two things follow
+ * from that, and both shape this class:
+ *
+ *   - The redirect cannot be built offline. The application first asks the
+ *     provider for a request token, and only then knows where to send the
+ *     user — so `redirectUrl()` throws here and `begin()` is the way in.
+ *   - There is no bearer token. Every call is SIGNED, request token included,
+ *     which is what `oauth1.ts` exists for.
+ *
+ * The CSRF check is the same idea as OAuth2's `state` under another name: the
+ * provider hands back the request token it was given, and it has to match the
+ * one this application issued. So it maps onto `callback(code, state,
+ * expectedState, secret)` without inventing a second shape — the verifier is
+ * the code, the returned token is the state, and the request-token secret is
+ * the secret kept from `begin()`.
+ */
+import type { OAuthConfig, OAuthToken, RedirectRequest, TransitDriver, TransitUser } from "./types.js";
+export declare abstract class Oauth1Driver implements TransitDriver {
+    #private;
+    protected readonly config: OAuthConfig;
+    /** Named in errors, so a failure says which provider refused. */
+    protected abstract readonly provider: string;
+    /** Where a request token is obtained, before anything else can happen. */
+    protected abstract readonly requestTokenUrl: string;
+    /** Where the user approves. */
+    protected abstract readonly authorizeUrl: string;
+    /** Where the request token is traded for an access token. */
+    protected abstract readonly accessTokenUrl: string;
+    /** Where the profile is read. */
+    protected abstract readonly userInfoUrl: string;
+    constructor(config: OAuthConfig);
+    /** Extra query parameters this provider wants on the profile request. */
+    protected userInfoParams(): Record<string, string>;
+    /** Turn this provider's profile payload into the shape Warden hands back. */
+    protected abstract mapUser(raw: Record<string, unknown>): TransitUser;
+    /**
+     * OAuth1 has no offline redirect: the URL carries a request token that only
+     * the provider can issue. Saying so is more useful than returning a URL
+     * that would be refused.
+     */
+    redirectUrl(): string;
+    /**
+     * Ask for a request token, and answer with where to send the user plus the
+     * two values to keep: the token, which the callback has to match, and its
+     * secret, without which the exchange cannot be signed.
+     */
+    begin(): Promise<RedirectRequest>;
+    /**
+     * `code` is the `oauth_verifier`, `state` the `oauth_token` the provider
+     * sent back, `expectedState` the one issued at `begin()`, and `secret` its
+     * secret.
+     */
+    callback(code: string, state?: string, expectedState?: string, secret?: string): Promise<{
+        user: TransitUser;
+        token: OAuthToken;
+    }>;
+    /**
+     * Read the profile behind a token already held. Unlike OAuth2 this needs
+     * the secret too — an OAuth1 token alone signs nothing.
+     */
+    userFromToken(accessToken: string, tokenSecret?: string): Promise<TransitUser>;
+    /** Read the profile with a signed GET. */
+    protected fetchUser(accessToken: string, tokenSecret: string): Promise<TransitUser>;
+}
+//# sourceMappingURL=Oauth1Driver.d.ts.map

package/dist/Oauth1Driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Oauth1Driver.d.ts","sourceRoot":"","sources":["../src/Oauth1Driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EACX,WAAW,EACX,UAAU,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACX,MAAM,YAAY,CAAC;AAGpB,8BAAsB,YAAa,YAAW,aAAa;;IAY9C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW;IAXlD,iEAAiE;IACjE,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC7C,0EAA0E;IAC1E,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACpD,+BAA+B;IAC/B,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IACjD,6DAA6D;IAC7D,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IACnD,iCAAiC;IACjC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,MAAM,EAAE,WAAW;IAElD,yEAAyE;IACzE,SAAS,CAAC,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlD,6EAA6E;IAC7E,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW;IAErE;;;;OAIG;IACH,WAAW,IAAI,MAAM;IAMrB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,eAAe,CAAC;IA2BvC;;;;OAIG;IACG,QAAQ,CACb,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC;IAsBpD;;;OAGG;IACG,aAAa,CAClB,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC;IASvB,0CAA0C;cAC1B,SAAS,CACxB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,CAAC;CA8DvB"}

package/dist/Oauth1Driver.js

@@ -0,0 +1,148 @@
+/**
+ * The OAuth 1.0a three-legged flow.
+ *
+ * A different protocol from OAuth2, not a variation on it. Two things follow
+ * from that, and both shape this class:
+ *
+ *   - The redirect cannot be built offline. The application first asks the
+ *     provider for a request token, and only then knows where to send the
+ *     user — so `redirectUrl()` throws here and `begin()` is the way in.
+ *   - There is no bearer token. Every call is SIGNED, request token included,
+ *     which is what `oauth1.ts` exists for.
+ *
+ * The CSRF check is the same idea as OAuth2's `state` under another name: the
+ * provider hands back the request token it was given, and it has to match the
+ * one this application issued. So it maps onto `callback(code, state,
+ * expectedState, secret)` without inventing a second shape — the verifier is
+ * the code, the returned token is the state, and the request-token secret is
+ * the secret kept from `begin()`.
+ */
+import { authorizationHeader, baseOauthParams, nonce, parseFormBody, } from "./oauth1.js";
+import { assertOAuthState } from "./types.js";
+export class Oauth1Driver {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Extra query parameters this provider wants on the profile request. */
+    userInfoParams() {
+        return {};
+    }
+    /**
+     * OAuth1 has no offline redirect: the URL carries a request token that only
+     * the provider can issue. Saying so is more useful than returning a URL
+     * that would be refused.
+     */
+    redirectUrl() {
+        throw new Error(`[transit] ${this.provider} uses OAuth1, whose redirect needs a request token from the provider. Use begin() instead of redirect().`);
+    }
+    /**
+     * Ask for a request token, and answer with where to send the user plus the
+     * two values to keep: the token, which the callback has to match, and its
+     * secret, without which the exchange cannot be signed.
+     */
+    async begin() {
+        const oauth = this.#oauth();
+        oauth.push(["oauth_callback", this.config.callbackUrl]);
+        const body = await this.#post(this.requestTokenUrl, oauth);
+        if (body.oauth_callback_confirmed !== "true") {
+            // The provider rejects a callback URL it does not have registered,
+            // and says so here rather than at the end of the flow.
+            throw new Error(`${this.provider} did not confirm the callback URL — check that '${this.config.callbackUrl}' is registered on the application.`);
+        }
+        const token = body.oauth_token;
+        const secret = body.oauth_token_secret;
+        if (!token || !secret) {
+            throw new Error(`${this.provider} OAuth: no request token in the response`);
+        }
+        return {
+            url: `${this.authorizeUrl}?oauth_token=${encodeURIComponent(token)}`,
+            state: token,
+            secret,
+        };
+    }
+    /**
+     * `code` is the `oauth_verifier`, `state` the `oauth_token` the provider
+     * sent back, `expectedState` the one issued at `begin()`, and `secret` its
+     * secret.
+     */
+    async callback(code, state, expectedState, secret) {
+        assertOAuthState(state, expectedState);
+        if (!secret) {
+            throw new Error(`[transit] ${this.provider} needs the request-token secret from begin() — store it with the token and pass it back here.`);
+        }
+        const oauth = this.#oauth(expectedState);
+        oauth.push(["oauth_verifier", code]);
+        const body = await this.#post(this.accessTokenUrl, oauth, secret);
+        const accessToken = body.oauth_token;
+        const tokenSecret = body.oauth_token_secret;
+        if (!accessToken || !tokenSecret) {
+            throw new Error(`${this.provider} OAuth: no access token in response`);
+        }
+        const user = await this.fetchUser(accessToken, tokenSecret);
+        return { user, token: { accessToken, tokenSecret } };
+    }
+    /**
+     * Read the profile behind a token already held. Unlike OAuth2 this needs
+     * the secret too — an OAuth1 token alone signs nothing.
+     */
+    async userFromToken(accessToken, tokenSecret) {
+        if (!tokenSecret) {
+            throw new Error(`[transit] ${this.provider} needs the token secret as well: an OAuth1 access token cannot sign a request on its own.`);
+        }
+        return this.fetchUser(accessToken, tokenSecret);
+    }
+    /** Read the profile with a signed GET. */
+    async fetchUser(accessToken, tokenSecret) {
+        const params = this.userInfoParams();
+        const query = new URLSearchParams(params).toString();
+        const url = query ? `${this.userInfoUrl}?${query}` : this.userInfoUrl;
+        const response = await fetch(url, {
+            headers: {
+                Authorization: authorizationHeader({
+                    method: "GET",
+                    url,
+                    oauth: this.#oauth(accessToken),
+                    consumerSecret: this.config.clientSecret,
+                    tokenSecret,
+                }),
+                Accept: "application/json",
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`${this.provider} profile request failed (HTTP ${response.status})`);
+        }
+        return this.mapUser((await response.json()));
+    }
+    /** The `oauth_*` set for one request, stamped now. */
+    #oauth(token) {
+        return baseOauthParams({
+            consumerKey: this.config.clientId,
+            token,
+            timestamp: Math.floor(Date.now() / 1000),
+            nonce: nonce(),
+        });
+    }
+    /** A signed POST to one of the token endpoints, whose body is form-encoded. */
+    async #post(url, oauth, tokenSecret) {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: authorizationHeader({
+                    method: "POST",
+                    url,
+                    oauth,
+                    consumerSecret: this.config.clientSecret,
+                    tokenSecret,
+                }),
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`${this.provider} OAuth token exchange failed (HTTP ${response.status})`);
+        }
+        // These endpoints answer `key=value&…`, not JSON.
+        return parseFormBody(await response.text());
+    }
+}
+//# sourceMappingURL=Oauth1Driver.js.map

package/dist/Oauth1Driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Oauth1Driver.js","sourceRoot":"","sources":["../src/Oauth1Driver.ts"],"names":[],"mappings":"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"}

package/dist/Oauth2Driver.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The half of an OAuth2 sign-in every provider shares.
+ *
+ * Each provider differs in three places — where you send the user, where the
+ * code is exchanged, and what the profile payload is called — and agrees on
+ * everything else. This holds the everything else, so a driver is the three
+ * URLs, the default scopes, and the mapping from that provider's payload to
+ * {@link TransitUser}.
+ *
+ * Nothing here is stateful: the `state` and, where a provider requires it, the
+ * PKCE verifier are passed in and handed back by the caller. Warden does not
+ * own your session, so it cannot store them for you — and that is also what
+ * lets one driver serve several concurrent sign-ins.
+ */
+import type { OAuthConfig, OAuthToken, RedirectRequest, TransitDriver, TransitUser } from "./types.js";
+/** A provider's token response, before it is narrowed. */
+type TokenResponse = Record<string, unknown>;
+/**
+ * Mint a PKCE code verifier.
+ *
+ * Store it next to the `state` — the same place, with the same lifetime — and
+ * hand it back to `callback()`. A provider that requires PKCE binds the
+ * authorization code to this value, so a code intercepted on its way back is
+ * useless to whoever intercepted it.
+ */
+export declare function createCodeVerifier(): string;
+export declare abstract class Oauth2Driver implements TransitDriver {
+    #private;
+    protected readonly config: OAuthConfig;
+    /** Named in errors, so a failure says which provider refused. */
+    protected abstract readonly provider: string;
+    /** Where the user is sent to approve. */
+    protected abstract readonly authorizeUrl: string;
+    /** Where the authorization code is exchanged for a token. */
+    protected abstract readonly accessTokenUrl: string;
+    /** Where the profile is read. */
+    protected abstract readonly userInfoUrl: string;
+    /** Scopes requested when the config names none. */
+    protected abstract readonly defaultScopes: readonly string[];
+    /**
+     * Providers that require PKCE. The redirect then refuses to build without
+     * a verifier rather than sending the user to a URL the provider rejects.
+     */
+    protected readonly requiresPkce: boolean;
+    /**
+     * Send the client credentials as HTTP Basic on the token request instead of
+     * in the body. A handful of providers accept nothing else.
+     */
+    protected readonly tokenAuth: "body" | "basic";
+    constructor(config: OAuthConfig);
+    /** Extra parameters this provider wants on the authorize URL. */
+    protected authorizeParams(): Record<string, string>;
+    /** Extra query parameters this provider wants on the profile request. */
+    protected userInfoParams(): Record<string, string>;
+    /** Turn this provider's profile payload into the shape Warden hands back. */
+    protected abstract mapUser(raw: Record<string, unknown>): TransitUser;
+    scopes(): string[];
+    redirectUrl(state?: string, secret?: string): string;
+    /**
+     * Where to send the user, plus what has to be kept until they come back.
+     * The state is minted here when the caller has no reason to choose one,
+     * and a provider requiring PKCE gets its verifier without the caller
+     * having to know it needed one.
+     */
+    begin(state?: string): Promise<RedirectRequest>;
+    callback(code: string, state?: string, expectedState?: string, secret?: string): Promise<{
+        user: TransitUser;
+        token: OAuthToken;
+    }>;
+    /**
+     * Read the profile behind a token you already hold, with no code to
+     * exchange — a refreshed token, or one a mobile client obtained itself.
+     */
+    userFromToken(accessToken: string): Promise<TransitUser>;
+    /** Trade the authorization code for an access token. */
+    protected exchange(code: string, secret?: string): Promise<TokenResponse>;
+    /** Read the profile. Providers needing a second call override this. */
+    protected fetchUser(accessToken: string): Promise<TransitUser>;
+    /** An authenticated GET returning a JSON array — some endpoints answer one. */
+    protected getList(url: string, accessToken: string, params?: Record<string, string>): Promise<unknown[]>;
+    /** An authenticated GET returning the decoded JSON body. */
+    protected get(url: string, accessToken: string, params?: Record<string, string>): Promise<Record<string, unknown>>;
+}
+/** The S256 challenge a provider compares the verifier against. */
+export declare function challengeFor(secret: string): string;
+/** Read a string field, or `undefined` when it is absent or not a string. */
+export declare function str(raw: Record<string, unknown>, key: string): string | undefined;
+export {};
+//# sourceMappingURL=Oauth2Driver.d.ts.map

package/dist/Oauth2Driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Oauth2Driver.d.ts","sourceRoot":"","sources":["../src/Oauth2Driver.ts"],"names":[],"mappings":"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"}