work in progress
This commit is contained in:
Generated
+65
@@ -0,0 +1,65 @@
|
||||
{
|
||||
"name": "locqr-sdk",
|
||||
"version": "0.1.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "locqr-sdk",
|
||||
"version": "0.1.0",
|
||||
"devDependencies": {
|
||||
"@types/chrome": "^0.0.280",
|
||||
"typescript": "^5.6.0"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/chrome": {
|
||||
"version": "0.0.280",
|
||||
"resolved": "https://registry.npmjs.org/@types/chrome/-/chrome-0.0.280.tgz",
|
||||
"integrity": "sha512-AotSmZrL9bcZDDmSI1D9dE7PGbhOur5L0cKxXd7IqbVizQWCY4gcvupPUVsQ4FfDj3V2tt/iOpomT9EY0s+w1g==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@types/filesystem": "*",
|
||||
"@types/har-format": "*"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/filesystem": {
|
||||
"version": "0.0.36",
|
||||
"resolved": "https://registry.npmjs.org/@types/filesystem/-/filesystem-0.0.36.tgz",
|
||||
"integrity": "sha512-vPDXOZuannb9FZdxgHnqSwAG/jvdGM8Wq+6N4D/d80z+D4HWH+bItqsZaVRQykAn6WEVeEkLm2oQigyHtgb0RA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@types/filewriter": "*"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/filewriter": {
|
||||
"version": "0.0.33",
|
||||
"resolved": "https://registry.npmjs.org/@types/filewriter/-/filewriter-0.0.33.tgz",
|
||||
"integrity": "sha512-xFU8ZXTw4gd358lb2jw25nxY9QAgqn2+bKKjKOYfNCzN4DKCFetK7sPtrlpg66Ywe3vWY9FNxprZawAh9wfJ3g==",
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/@types/har-format": {
|
||||
"version": "1.2.16",
|
||||
"resolved": "https://registry.npmjs.org/@types/har-format/-/har-format-1.2.16.tgz",
|
||||
"integrity": "sha512-fluxdy7ryD3MV6h8pTfTYpy/xQzCFC7m89nOH9y94cNqJ1mDIDPut7MnRHI3F6qRmh/cT2fUjG1MLdCNb4hE9A==",
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/typescript": {
|
||||
"version": "5.9.3",
|
||||
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
|
||||
"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
|
||||
"dev": true,
|
||||
"license": "Apache-2.0",
|
||||
"bin": {
|
||||
"tsc": "bin/tsc",
|
||||
"tsserver": "bin/tsserver"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=14.17"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"name": "locqr-sdk",
|
||||
"private": true,
|
||||
"version": "0.1.0",
|
||||
"description": "LOCQR JS SDK — thin bridge between a website and the extension's Port. See sdk/claude.md.",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"build": "tsc"
|
||||
},
|
||||
"dependencies": {},
|
||||
"devDependencies": {
|
||||
"@types/chrome": "^0.0.280",
|
||||
"typescript": "^5.6.0"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,180 @@
|
||||
// LOCQR JS SDK — a thin bridge, per sdk/claude.md: "no logic of its own,"
|
||||
// no cryptography, no state beyond the Port connection itself. Wraps
|
||||
// chrome.runtime.connect(extensionId) — the Port protocol is normative in
|
||||
// interfaces.md; this file only translates it into locqr.init()/ready/
|
||||
// requestCredential()/on()/off().
|
||||
|
||||
export type LocqrErrorCode = 'NOT_INSTALLED' | 'NOT_REGISTERED' | 'CERT_INVALID' | 'ACCOUNT_ERROR' | 'RUN_FAILED';
|
||||
|
||||
export interface LocqrError {
|
||||
code: LocqrErrorCode;
|
||||
reason?: string;
|
||||
security?: boolean;
|
||||
}
|
||||
|
||||
export interface InitOptions {
|
||||
cert: string;
|
||||
/** Required for real external-page connections in practice — the dev
|
||||
* build's extension ID is not the same as the Store-published one
|
||||
* (sdk/claude.md, "Extension ID in development"). */
|
||||
extensionId?: string;
|
||||
}
|
||||
|
||||
interface ReadyPayload {
|
||||
features: string[];
|
||||
}
|
||||
|
||||
export interface Credential {
|
||||
username: string;
|
||||
password: string;
|
||||
}
|
||||
|
||||
interface EventPayloads {
|
||||
ready: ReadyPayload;
|
||||
'run:started': Record<string, never>;
|
||||
'run:delivered': { credential: Credential };
|
||||
'run:error': { error: LocqrError };
|
||||
}
|
||||
|
||||
type LocqrEvent = keyof EventPayloads;
|
||||
type EventHandler<E extends LocqrEvent = LocqrEvent> = (payload: EventPayloads[E]) => void;
|
||||
|
||||
interface VerificationValidMessage {
|
||||
type: 'verification';
|
||||
status: 'valid';
|
||||
features: string[];
|
||||
}
|
||||
interface VerificationErrorMessage {
|
||||
type: 'verification';
|
||||
status: 'error';
|
||||
error: LocqrError;
|
||||
}
|
||||
interface RunStartedMessage {
|
||||
type: 'run_started';
|
||||
}
|
||||
interface RunDeliveredMessage {
|
||||
type: 'run_delivered';
|
||||
credential: Credential;
|
||||
}
|
||||
interface RunErrorMessage {
|
||||
type: 'run_error';
|
||||
error: LocqrError;
|
||||
}
|
||||
type ExtensionMessage = VerificationValidMessage | VerificationErrorMessage | RunStartedMessage | RunDeliveredMessage | RunErrorMessage;
|
||||
|
||||
function notInstalled(): Promise<never> {
|
||||
return Promise.reject<never>({ code: 'NOT_INSTALLED' } satisfies LocqrError);
|
||||
}
|
||||
|
||||
class Locqr {
|
||||
private port: chrome.runtime.Port | null = null;
|
||||
private readyPromise: Promise<ReadyPayload> = notInstalled();
|
||||
private readonly handlers = new Map<LocqrEvent, Set<EventHandler>>();
|
||||
private settled = false;
|
||||
// requestCredential()'s pending settlers — one run at a time, per sdk/claude.md
|
||||
// (mixing the Promise and event models on the same run is not supported;
|
||||
// this SDK stays a thin bridge and doesn't police that, it just tracks
|
||||
// the single in-flight requestCredential() call if there is one).
|
||||
private runResolvers: { resolve: (credential: Credential) => void; reject: (error: LocqrError) => void } | null = null;
|
||||
|
||||
init(options: InitOptions): void {
|
||||
this.settled = false;
|
||||
|
||||
if (typeof chrome === 'undefined' || !chrome.runtime?.connect) {
|
||||
// NOT_INSTALLED is produced locally — it never arrives over the wire
|
||||
// (interfaces.md, Port message protocol).
|
||||
this.readyPromise = notInstalled();
|
||||
this.readyPromise.catch(() => {});
|
||||
return;
|
||||
}
|
||||
|
||||
this.readyPromise = new Promise<ReadyPayload>((resolve, reject) => {
|
||||
const settle = (fn: () => void) => {
|
||||
if (this.settled) return;
|
||||
this.settled = true;
|
||||
fn();
|
||||
};
|
||||
|
||||
try {
|
||||
this.port = options.extensionId ? chrome.runtime.connect(options.extensionId) : chrome.runtime.connect();
|
||||
} catch {
|
||||
settle(() => reject({ code: 'NOT_INSTALLED' } satisfies LocqrError));
|
||||
return;
|
||||
}
|
||||
|
||||
this.port.onDisconnect.addListener(() => {
|
||||
// Disconnected before a verification response ever arrived —
|
||||
// the extension isn't there to talk to.
|
||||
settle(() => reject({ code: 'NOT_INSTALLED' } satisfies LocqrError));
|
||||
// A disconnect mid-run (e.g. the extension's service worker
|
||||
// was torn down) also ends any in-flight requestCredential().
|
||||
this.runResolvers?.reject({ code: 'RUN_FAILED', reason: 'backend_unreachable' });
|
||||
this.runResolvers = null;
|
||||
});
|
||||
|
||||
this.port.onMessage.addListener((message: ExtensionMessage) => {
|
||||
switch (message.type) {
|
||||
case 'verification':
|
||||
if (message.status === 'valid') {
|
||||
const payload: ReadyPayload = { features: message.features };
|
||||
this.emit('ready', payload);
|
||||
settle(() => resolve(payload));
|
||||
} else {
|
||||
settle(() => reject(message.error));
|
||||
}
|
||||
return;
|
||||
case 'run_started':
|
||||
this.emit('run:started', {});
|
||||
return;
|
||||
case 'run_delivered':
|
||||
this.emit('run:delivered', { credential: message.credential });
|
||||
this.runResolvers?.resolve(message.credential);
|
||||
this.runResolvers = null;
|
||||
return;
|
||||
case 'run_error':
|
||||
this.emit('run:error', { error: message.error });
|
||||
this.runResolvers?.reject(message.error);
|
||||
this.runResolvers = null;
|
||||
return;
|
||||
}
|
||||
});
|
||||
|
||||
this.port.postMessage({ type: 'init', cert: options.cert });
|
||||
});
|
||||
this.readyPromise.catch(() => {}); // consumer awaits `ready` on their own schedule
|
||||
}
|
||||
|
||||
get ready(): Promise<ReadyPayload> {
|
||||
return this.readyPromise;
|
||||
}
|
||||
|
||||
/** Triggers Phase 1. Resolves with the credential at the end of Phase 4, rejects on run_error. */
|
||||
requestCredential(): Promise<Credential> {
|
||||
if (!this.port) {
|
||||
return Promise.reject<Credential>({ code: 'NOT_INSTALLED' } satisfies LocqrError);
|
||||
}
|
||||
const port = this.port;
|
||||
return new Promise<Credential>((resolve, reject) => {
|
||||
this.runResolvers = { resolve, reject };
|
||||
port.postMessage({ type: 'request_credential' });
|
||||
});
|
||||
}
|
||||
|
||||
on<E extends LocqrEvent>(event: E, handler: EventHandler<E>): void {
|
||||
if (!this.handlers.has(event)) this.handlers.set(event, new Set());
|
||||
this.handlers.get(event)!.add(handler as EventHandler);
|
||||
}
|
||||
|
||||
off<E extends LocqrEvent>(event: E, handler: EventHandler<E>): void {
|
||||
this.handlers.get(event)?.delete(handler as EventHandler);
|
||||
}
|
||||
|
||||
private emit<E extends LocqrEvent>(event: E, payload: EventPayloads[E]): void {
|
||||
for (const handler of this.handlers.get(event) ?? []) {
|
||||
handler(payload);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const locqr = new Locqr();
|
||||
export default locqr;
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"lib": ["ES2022", "DOM"],
|
||||
"module": "ES2022",
|
||||
"moduleResolution": "Bundler",
|
||||
"strict": true,
|
||||
"types": ["chrome"],
|
||||
"outDir": "dist",
|
||||
"declaration": true
|
||||
},
|
||||
"include": ["src"]
|
||||
}
|
||||
Reference in New Issue
Block a user