@atmem/architect 0.0.0-stage → 0.2.0-alpha.4.1

package/src/runtime/enterprise_queries_schema.sql

@@ -0,0 +1,27 @@
+-- Fresh installation only. Queue and domain state share one transaction.
+CREATE TABLE enterprise_queries.schema_version(
+ version integer PRIMARY KEY CHECK(version=1),source_sha256 text NOT NULL,queue_version text NOT NULL
+);
+CREATE TABLE enterprise_queries.requests(
+ id uuid PRIMARY KEY,account_id text NOT NULL,principal_key text NOT NULL,
+ session_sha256 text NOT NULL,request_key uuid NOT NULL,
+ question_mac text NOT NULL,question_ciphertext text,
+ state text NOT NULL CHECK(state IN('queued','running','ready','failed','cancelled','expired')),
+ attempt integer NOT NULL DEFAULT 0 CHECK(attempt BETWEEN 0 AND 3),
+ lease_token uuid,lease_until timestamptz,result_ciphertext text,
+ error_code text CHECK(error_code IN('source','setup','signin','unavailable','answer')),
+ created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+ updated_at timestamptz NOT NULL DEFAULT clock_timestamp(),expires_at timestamptz NOT NULL,
+ UNIQUE(account_id,principal_key,session_sha256,request_key),
+ FOREIGN KEY(account_id,principal_key)REFERENCES enterprise_auth.memberships,
+ CHECK((state='running')=(lease_token IS NOT NULL AND lease_until IS NOT NULL)),
+ CHECK((state='ready')=(result_ciphertext IS NOT NULL))
+);
+CREATE INDEX enterprise_queries_requests_recovery ON enterprise_queries.requests(state,lease_until,expires_at);
+CREATE INDEX enterprise_queries_jobs_domain ON enterprise_queries.procrastinate_jobs((args->>'query_id'),task_name,status);
+CREATE TABLE enterprise_queries.events(
+ id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+ query_id uuid NOT NULL,account_id text NOT NULL,principal_key text NOT NULL,
+ event text NOT NULL CHECK(event IN('submitted','claimed','ready','released','retry_pending','failed','cancelled','expired')),
+ attempt integer NOT NULL,created_at timestamptz NOT NULL DEFAULT clock_timestamp()
+);

package/src/runtime/enterprise_query_service.py

@@ -0,0 +1,111 @@
+"""Native credential/engine composition for queued questions and delayed release."""
+import asyncio
+import threading
+import logging
+import procrastinate
+import psycopg
+from enterprise_queries import QueryLeaseLost
+from enterprise_sources import SourceDenied,SourceUnavailable,SourceChanged
+from public_faq import InvalidAnswer
+from enterprise_knowledge import current_engine
+from enterprise_audit import KnowledgeAudit
+
+
+class EnterpriseAnswers:
+    def __init__(self,store,connections,make_engine,*,extraction_cache=None,audit=None):
+        if not isinstance(connections,dict)or not 1<=len(connections)<=20 or not callable(make_engine):raise ValueError('Supply owned native question adapters')
+        if any(entry.driver.store is not store.auth for entry in connections.values()):raise ValueError('Question/source stores must use the same owned authority')
+        if extraction_cache is not None and(extraction_cache.auth is not store.auth or extraction_cache.account_id!=store.account_id):raise ValueError('Extraction cache must use the same owned company and authority')
+        if audit is not None and(not isinstance(audit,KnowledgeAudit)or audit.auth is not store.auth or audit.account_id!=store.account_id):raise ValueError('Question audit must use the same owned company and authority')
+        self.store=store;self.connections=connections;self.make_engine=make_engine;self.extraction_cache=extraction_cache;self.audit=audit
+
+    def engine(self,principal,authorize,*,query_id=None,attempt=None):
+        engine=current_engine(self.store.auth,self.connections,principal,self.make_engine,authorize)
+        if self.audit is not None:engine.audit=self.audit.bind(principal,query_id=query_id,attempt=attempt)
+        if self.extraction_cache is not None:
+            engine.decode=self.extraction_cache.wrap(engine.decode,lambda:engine.authorize(principal.key))
+        return engine
+
+    def execute(self,identity):
+        lease=self.store.claim(identity)
+        if lease is None:return
+        stop=threading.Event();lost=threading.Event()
+        def heartbeat():
+            while not stop.wait(max(1,self.store.lease_seconds//3)):
+                try:self.store.guard(lease,renew=True)
+                except Exception:lost.set();return
+        def authorize(subject):
+            if lost.is_set():raise QueryLeaseLost('Question worker lost current authority')
+            if subject!=lease.principal.key:raise SourceDenied('company_identity_required')
+            self.store.guard(lease)
+        thread=threading.Thread(target=heartbeat,daemon=True);thread.start()
+        try:
+            authorize(lease.principal.key)
+            engine=self.engine(lease.principal,authorize,query_id=lease.id,attempt=lease.attempt)
+            receipt=engine.answer_receipt(lease.question,lease.principal.key)
+            authorize(lease.principal.key)
+            self.store.complete(lease,receipt)
+        except QueryLeaseLost:return
+        except SourceDenied as error:
+            code='setup'if str(error)=='source_mapping_required'else'source'if str(error)in {'source_reconnection_required','source_consent_required'}else'signin'if str(error).startswith('company_')else'unavailable'
+            self.store.failed(lease,code,retry=code=='unavailable')
+        except InvalidAnswer:self.store.failed(lease,'answer')
+        except SourceUnavailable:self.store.failed(lease,'unavailable',retry=True)
+        except Exception:self.store.failed(lease,'unavailable')
+        finally:stop.set();thread.join(timeout=2)
+
+    def status(self,session,identity):
+        row=self.store.get(session,identity)
+        result={'id':identity,'status':row['state']}
+        if row['state']=='failed':result['errorCode']=row['error_code'];return result
+        if row['state']!='ready':return result
+        receipt=self.store.open_result(row)
+        def authorize(subject):
+            if subject!=session.principal.key:raise SourceDenied('company_identity_required')
+            current=self.store.get(session,identity)
+            if current['state']!='ready'or current['attempt']!=row['attempt']:raise QueryLeaseLost('Question changed before release')
+        try:
+            engine=self.engine(session.principal,authorize,query_id=identity,attempt=row['attempt'])
+            answer=engine.release(receipt,session.principal.key)
+            self.store.released(session,identity,row['attempt'])
+            return {**result,'result':answer}
+        except SourceChanged:
+            self.store.requeue(session,identity,row['attempt'])
+            return {'id':identity,'status':'queued'}
+        except QueryLeaseLost:
+            return {'id':identity,'status':self.store.get(session,identity)['state']}
+
+
+class EnterpriseQueryWorker:
+    def __init__(self,dsn,service,*,document_recovery=None):
+        if document_recovery is not None and not callable(document_recovery):raise ValueError('Use the owned document reconciler')
+        self.service=service
+        self.document_recovery=document_recovery
+        async def refresh():return await asyncio.to_thread(dsn)
+        self.app=procrastinate.App(connector=procrastinate.PsycopgConnector(conninfo=refresh if callable(dsn)else dsn,min_size=1,max_size=4,max_lifetime=600,kwargs={'connect_timeout':5,'options':'-c search_path=pg_catalog,enterprise_queries,pg_temp -c statement_timeout=10000 -c lock_timeout=3000'}))
+        async def execute(query_id):await asyncio.to_thread(service.execute,query_id)
+        self.task=self.app.task(name=service.store.task.name,queue=service.store.task.queue)(execute)
+
+    async def run(self,*,concurrency=2,**options):
+        if type(concurrency)is not int or not 1<=concurrency<=4:raise ValueError('Use bounded owned query concurrency')
+        async def recover():
+            while True:
+                try:
+                    await asyncio.to_thread(self.service.store.recover)
+                    if self.service.extraction_cache is not None:await asyncio.to_thread(self.service.extraction_cache.purge)
+                except(psycopg.OperationalError,SourceUnavailable):logging.getLogger(__name__).warning('Question recovery is temporarily unavailable')
+                await asyncio.sleep(15)
+        async def documents():
+            # Separate loop: slow native deletion never blocks query lease or
+            # cache recovery. SQL cleanup claims prevent overlapping ownership.
+            while True:
+                try:await asyncio.to_thread(self.document_recovery,limit=1)
+                except(psycopg.Error,SourceUnavailable):logging.getLogger(__name__).warning('Document cleanup is temporarily unavailable')
+                await asyncio.sleep(15)
+        async with self.app.open_async():
+            async with asyncio.TaskGroup()as group:
+                recovery=group.create_task(recover())
+                cleanup=group.create_task(documents())if self.document_recovery is not None else None
+                await self.app.run_worker_async(queues=[self.task.queue],concurrency=concurrency,**options)
+                recovery.cancel()
+                if cleanup is not None:cleanup.cancel()

package/src/runtime/enterprise_secrets.py

@@ -0,0 +1,110 @@
+"""Startup secret injections for the owned read-only private assistant.
+
+Native platforms resolve pinned secret references. This adapter never downloads
+cloud secrets, generates a replacement encryption key or writes into an export.
+All replicas must use the same reviewed encryption-key version; coordinated key
+migration/backup is separate operator work, not automatic hot rotation.
+"""
+import atexit
+import os
+from pathlib import Path
+import shutil
+import tempfile
+from cryptography.fernet import Fernet
+from enterprise_sources import SourceUnavailable
+
+FIELDS = {
+    'encryption': ('ENTERPRISE_ENCRYPTION_KEY', 'ENTERPRISE_ENCRYPTION_KEY_FILE', 44),
+    'graph': ('SHAREPOINT_CLIENT_SECRET', 'SHAREPOINT_CLIENT_SECRET_FILE', 16000),
+    'confluence': ('CONFLUENCE_CLIENT_SECRET', 'CONFLUENCE_CLIENT_SECRET_FILE', 16000),
+    'database_password': ('DATABASE_PASSWORD', 'DATABASE_PASSWORD_FILE', 500),
+    'database_ca': ('DATABASE_CA_PEM', 'DATABASE_CA_FILE', 256000),
+}
+
+
+def decode(name, raw):
+    if not raw or len(raw) > FIELDS[name][2] or b'\0' in raw:
+        raise ValueError('Invalid owned secret value')
+    value = raw.decode('utf-8')
+    if name == 'encryption':
+        if len(raw) != 44:
+            raise ValueError('Use the existing exact Fernet key')
+        Fernet(raw)
+    if name == 'database_ca' and '-----BEGIN CERTIFICATE-----' not in value:
+        raise ValueError('Use the native database CA certificate')
+    return value
+
+
+class SecretFiles:
+    def __init__(self, provider, environment, role):
+        if provider not in {'aws', 'azure', 'gcp', 'ibm'} or role not in {'api', 'worker', 'operator'}:
+            raise ValueError('Supply the owned private workload provider and role')
+        # Read-only assistants have no action credentials. Native workload
+        # identities must not silently fall back to inherited developer keys.
+        forbidden = ['DESTINATION_TOKEN', 'DESTINATION_TOKEN_FILE', 'PARSER_SHARED_TOKEN', 'PARSER_SHARED_TOKEN_FILE',
+                     'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN', 'AZURE_CLIENT_SECRET',
+                     'GOOGLE_APPLICATION_CREDENTIALS', 'IBMCLOUD_API_KEY', 'OPENAI_API_KEY']
+        if provider != 'ibm': forbidden += ['DATABASE_PASSWORD', 'DATABASE_PASSWORD_FILE']
+        if role == 'operator': forbidden += [value for name in ['encryption', 'graph', 'confluence'] for value in FIELDS[name][:2]]
+        if any(key in environment for key in forbidden):
+            raise ValueError('Unexpected static cloud, parser or action authority in the private workload')
+        self.env, self.directory, self.closed = dict(environment), None, False
+        required = ['encryption', 'graph', 'confluence'] if role != 'operator' else []
+        if provider != 'gcp': required.append('database_ca')
+        if provider == 'ibm': required.append('database_password')
+        selected = []
+        for name, (direct, pointer, maximum) in FIELDS.items():
+            if direct in environment and pointer in environment:
+                raise ValueError('Conflicting native secret injection and mounted file')
+            if direct in environment:
+                value = environment[direct]
+                if not isinstance(value, str): raise ValueError('Invalid native secret injection')
+                decode(name, value.encode('utf-8'))
+                selected.append((name, direct, pointer, value))
+            elif pointer in environment:
+                path = environment[pointer]
+                if not isinstance(path, str) or not Path(path).is_absolute():
+                    raise ValueError('Use the owned mounted secret path')
+            elif name in required:
+                raise ValueError('Missing required native secret reference')
+        try:
+            if selected:
+                self.directory = Path(tempfile.mkdtemp(prefix='atmem-enterprise-secrets-'))
+                self.directory.chmod(0o700)
+                for name, direct, pointer, value in selected:
+                    path = self.directory / name
+                    descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+                    with os.fdopen(descriptor, 'wb') as stream: stream.write(value.encode('utf-8'))
+                    self.env[pointer] = str(path); self.env.pop(direct, None)
+            # Fail startup for unreadable/invalid required files; do not generate
+            # new keys, invent credentials or defer broken setup to a basic user.
+            for name in required: self.read(name)
+            if environment is os.environ:
+                for _, direct, _, _ in selected: os.environ.pop(direct, None)
+            atexit.register(self.close)
+        except BaseException:
+            self.close(); raise
+
+    def __repr__(self): return '<Owned private-assistant secret files>'
+
+    def read(self, name):
+        if name not in FIELDS: raise ValueError('Unknown owned secret purpose')
+        try:
+            if self.closed: raise ValueError()
+            _, pointer, maximum = FIELDS[name]
+            path = self.env[pointer]
+            with Path(path).open('rb') as stream: raw = stream.read(maximum + 1)
+            return decode(name, raw)
+        except Exception:
+            raise SourceUnavailable('enterprise_secret_unavailable') from None
+
+    def reader(self, name):
+        if name not in FIELDS: raise ValueError('Unknown owned secret purpose')
+        return lambda: self.read(name)
+
+    def close(self):
+        if self.directory is not None: shutil.rmtree(self.directory, ignore_errors=True)
+        self.closed = True
+
+    def __enter__(self): return self
+    def __exit__(self, *args): self.close()

package/src/runtime/enterprise_sessions.py

@@ -0,0 +1,95 @@
+"""Opaque, durable company sessions; raw cookies/JWTs never persist in SQL."""
+from dataclasses import dataclass,field
+import hmac
+import secrets
+import time
+import re
+from enterprise_auth_store import digest,secret_binding
+from enterprise_identity import CompanyPrincipal
+from enterprise_sources import SourceDenied
+
+
+@dataclass(frozen=True)
+class BrowserSession:
+    principal: CompanyPrincipal
+    id: str = field(repr=False)
+    browser_nonce: str = field(repr=False)
+    csrf_sha256: str = field(repr=False)
+    csrf: str = field(repr=False)
+
+    def require_csrf(self,token):
+        secret_binding(token)
+        if not hmac.compare_digest(digest(token),self.csrf_sha256):raise SourceDenied('browser_request_denied')
+
+
+@dataclass(frozen=True)
+class CreatedSession:
+    token: str = field(repr=False)
+    csrf: str = field(repr=False)
+    max_age: int
+
+
+class CompanySessions:
+    def __init__(self,auth,*,domain=None):
+        if domain is not None and(not isinstance(domain,str)or not re.fullmatch('[0-9a-f]{64}',domain)):raise ValueError('Use the owned company session domain')
+        if getattr(auth,'company_domain',None)!=domain:raise ValueError('Session and authority company registrations must match')
+        self.auth=auth;self.domain=domain
+    def context(self,account,key,session):
+        result=['browser-session',account,key,session]
+        if self.domain is not None:result+=['company-registration',self.domain]
+        return result
+
+    def private(self,row,identity):
+        try:
+            private=self.auth.box.open(self.context(row['account_id'],row['principal_key'],identity),row['nonce_ciphertext'])
+            if set(private)!={'browser_nonce','csrf'}:raise ValueError()
+            secret_binding(private['browser_nonce']);secret_binding(private['csrf'])
+            if not hmac.compare_digest(digest(private['csrf']),row['csrf_sha256']):raise ValueError()
+            return private
+        except Exception:raise SourceDenied('company_identity_required')from None
+
+    def create(self,principal,previous=None):
+        if previous:
+            try:secret_binding(previous)
+            except SourceDenied:previous=None
+        token=secrets.token_urlsafe(32);csrf=secrets.token_urlsafe(32);nonce=secrets.token_urlsafe(32);identity=digest(token)
+        with self.auth.transaction()as cur:
+            self.auth._authorize(cur,principal)
+            previous_owner=cur.execute('SELECT account_id,principal_key FROM enterprise_auth.sessions WHERE session_sha256=%s',(digest(previous),)).fetchone()if previous else None
+            owners={principal.key}
+            if previous_owner and previous_owner['account_id']==principal.account_id:owners.add(previous_owner['principal_key'])
+            # A profile switch touches the prior person's browser row and the new
+            # person's quota. Lock both owner domains in one deterministic order.
+            for owner in sorted(owners):cur.execute('SELECT pg_advisory_xact_lock(hashtextextended(%s,0))',('enterprise-session:'+principal.account_id+':'+owner,))
+            if previous_owner and previous_owner['account_id']==principal.account_id:
+                row=cur.execute('SELECT account_id,principal_key,nonce_ciphertext,csrf_sha256,revoked_at,expires_at>clock_timestamp()AS current FROM enterprise_auth.sessions WHERE session_sha256=%s FOR UPDATE',(digest(previous),)).fetchone()
+                if row and row['account_id']==principal.account_id:
+                    if row['principal_key']==principal.key and row['current']and row['revoked_at']is None:
+                        try:nonce=self.private(row,digest(previous))['browser_nonce']
+                        except SourceDenied:pass # New verified login gets a fresh nonce; never inherit an invalid/old-domain one.
+                    cur.execute('UPDATE enterprise_auth.sessions SET revoked_at=clock_timestamp()WHERE session_sha256=%s',(digest(previous),))
+            cur.execute("DELETE FROM enterprise_auth.sessions WHERE account_id=%s AND principal_key=%s AND expires_at<clock_timestamp()-interval '1 day'",(principal.account_id,principal.key))
+            cur.execute('UPDATE enterprise_auth.sessions SET revoked_at=clock_timestamp()WHERE session_sha256 IN(SELECT session_sha256 FROM enterprise_auth.sessions WHERE account_id=%s AND principal_key=%s AND revoked_at IS NULL ORDER BY created_at DESC OFFSET 9)',(principal.account_id,principal.key))
+            encrypted=self.auth.box.seal(self.context(principal.account_id,principal.key,identity),{'browser_nonce':nonce,'csrf':csrf})
+            cur.execute('INSERT INTO enterprise_auth.sessions(session_sha256,account_id,principal_key,csrf_sha256,nonce_ciphertext,expires_at)VALUES(%s,%s,%s,%s,%s,to_timestamp(%s))',(identity,principal.account_id,principal.key,digest(csrf),encrypted,principal.expires_at))
+            self.auth.event(cur,principal,'company-session','session_started')
+        return CreatedSession(token,csrf,max(1,min(3600,int(principal.expires_at-time.time()))))
+
+    def authenticate(self,token):
+        try:secret_binding(token)
+        except SourceDenied:raise SourceDenied('company_identity_required')from None
+        identity=digest(token)
+        with self.auth.transaction()as cur:
+            row=cur.execute('SELECT s.account_id,s.principal_key,s.csrf_sha256,s.nonce_ciphertext,extract(epoch FROM s.expires_at)::bigint AS expires_at,m.issuer,m.subject FROM enterprise_auth.sessions s JOIN enterprise_auth.memberships m USING(account_id,principal_key)WHERE s.session_sha256=%s AND s.revoked_at IS NULL AND s.expires_at>clock_timestamp()',(identity,)).fetchone()
+            if not row:raise SourceDenied('company_identity_required')
+            principal=CompanyPrincipal(row['account_id'],row['issuer'],row['subject'],row['expires_at'])
+            if principal.key!=row['principal_key']:raise SourceDenied('company_identity_required')
+            self.auth._authorize(cur,principal)
+            private=self.private(row,identity);nonce=private['browser_nonce'];csrf=private['csrf']
+        return BrowserSession(principal,identity,nonce,row['csrf_sha256'],csrf)
+
+    def revoke(self,session):
+        with self.auth.transaction()as cur:
+            self.auth._authorize(cur,session.principal)
+            cur.execute('UPDATE enterprise_auth.sessions SET revoked_at=clock_timestamp()WHERE session_sha256=%s AND account_id=%s AND principal_key=%s',(session.id,session.principal.account_id,session.principal.key))
+            self.auth.event(cur,session.principal,'company-session','session_ended')

package/src/runtime/enterprise_sources.py

@@ -0,0 +1,260 @@
+"""Native read-only SharePoint/Confluence source boundary.
+
+Per-user delegated credentials come from a trusted OAuth broker, never chat/model
+input or a shared crawler identity. No private documents or permissions are cached.
+These API adapters do not implement that broker, an index, or the model API.
+"""
+from dataclasses import dataclass, field
+from html.parser import HTMLParser
+import json
+import re
+import time
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode, urlsplit, unquote
+from urllib.request import Request, build_opener, HTTPRedirectHandler, ProxyHandler
+
+
+class SourceUnavailable(RuntimeError):
+    pass
+
+
+class SourceDenied(SourceUnavailable):
+    pass
+
+
+class SourceChanged(SourceUnavailable):
+    pass
+
+
+@dataclass(frozen=True)
+class DelegatedAccess:
+    subject: str
+    source_subject: str
+    token: str = field(repr=False)
+    expires_at: float
+    kind: str = 'delegated'
+
+    def require(self, subject, now=None):
+        now=time.time()if now is None else now
+        if self.kind!='delegated'or not subject or self.subject!=subject or not self.source_subject or not isinstance(self.token,str)or not self.token or len(self.token)>32768 or any(c in self.token for c in '\r\n')or not isinstance(self.expires_at,(int,float))or isinstance(self.expires_at,bool)or not now+5<self.expires_at<now+86401:
+            raise SourceDenied('source_identity_unavailable')
+
+
+@dataclass(frozen=True)
+class SourceDocument:
+    source: str
+    id: str
+    version: str
+    title: str = field(repr=False)
+    text: str = field(repr=False)
+    url: str = field(repr=False)
+
+
+@dataclass(frozen=True)
+class Reply:
+    status: int
+    headers: dict
+    body: bytes = field(repr=False)
+
+
+def checked_url(url,hosts):
+    try:parts=urlsplit(url);port=parts.port
+    except (TypeError,ValueError):raise SourceUnavailable('invalid_source_url')from None
+    if parts.scheme!='https'or parts.hostname not in hosts or port not in {None,443}or parts.username or parts.password or parts.fragment or len(url)>16000 or any(c in url for c in '\r\n'):
+        raise SourceUnavailable('invalid_source_url')
+    return url
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self,request,fp,code,msg,headers,newurl):
+        return None
+
+
+class NativeHttp:
+    def __init__(self):
+        # A source bearer token must not be routed through environment proxies.
+        self.opener=build_opener(ProxyHandler({}),NoRedirect())
+
+    def get(self,url,token,*,hosts,limit=2000000):
+        checked_url(url,hosts)
+        headers={'Accept':'application/json','Cache-Control':'no-store'}
+        if token:headers['Authorization']='Bearer '+token
+        try:
+            response=self.opener.open(Request(url,headers=headers),timeout=10)
+        except HTTPError as error:
+            try:
+                if error.code in {301,302,303,307,308}:
+                    return Reply(error.code,dict(error.headers),b'')
+                if error.code in {401,403,404,410}:raise SourceDenied('source_access_denied')from None
+                raise SourceUnavailable('source_request_failed')from None
+            finally:error.close()
+        except (URLError,OSError,ValueError):raise SourceUnavailable('source_request_failed')from None
+        with response:
+            body=response.read(limit+1)
+            if len(body)>limit:raise SourceUnavailable('source_response_too_large')
+            return Reply(response.status,dict(response.headers),body)
+
+
+def decoded(reply):
+    if reply.status!=200:raise SourceUnavailable('source_response_failed')
+    try:value=json.loads(reply.body)
+    except (ValueError,UnicodeError):raise SourceUnavailable('invalid_source_response')from None
+    if not isinstance(value,dict):raise SourceUnavailable('invalid_source_response')
+    return value
+
+
+def identifier(value):
+    if not isinstance(value,str)or not re.fullmatch(r'[A-Za-z0-9_!.,-]{1,256}',value):raise SourceUnavailable('invalid_source_identifier')
+    return quote(value,safe='')
+
+
+def query_text(value):
+    if not isinstance(value,str)or not value.strip()or len(value)>1000 or any(ord(c)<32 for c in value):raise SourceUnavailable('invalid_source_query')
+    return value.strip()
+
+
+class GraphSharePoint:
+    def __init__(self,drive_id,sharepoint_host,access,*,http=None):
+        self.drive_id=drive_id;self.drive=identifier(drive_id);self.source='sharepoint:'+drive_id
+        if not isinstance(sharepoint_host,str)or not re.fullmatch(r'[a-z0-9][a-z0-9-]*\.sharepoint\.com',sharepoint_host):raise SourceUnavailable('invalid_sharepoint_host')
+        self.host=sharepoint_host;self.access=access;self.http=http or NativeHttp()
+        self.base='https://graph.microsoft.com/v1.0'
+
+    def _get(self,path,subject):
+        self.access.require(subject)
+        return decoded(self.http.get(self.base+path,self.access.token,hosts={'graph.microsoft.com'}))
+
+    def identify(self,subject):
+        if self._get('/me?$select=id',subject).get('id')!=self.access.source_subject:raise SourceDenied('source_identity_mismatch')
+
+    def search(self,question,subject,*,limit=20):
+        if type(limit)is not int or not 1<=limit<=100:raise SourceUnavailable('invalid_search_limit')
+        self.identify(subject)
+        q=quote(query_text(question).replace("'","''"),safe='')
+        route=f"/drives/{self.drive}/root/search(q='{q}')"
+        url=self.base+route+'?'+urlencode({'$top':min(limit,100),'$select':'id,file,parentReference'})
+        result=[];seen=set();pages=set()
+        while url and len(result)<limit:
+            checked_url(url,{'graph.microsoft.com'})
+            if unquote(urlsplit(url).path)!=unquote(urlsplit(self.base+route).path)or url in pages or len(pages)>=20:raise SourceUnavailable('invalid_source_paging')
+            pages.add(url);self.access.require(subject)
+            value=decoded(self.http.get(url,self.access.token,hosts={'graph.microsoft.com'}))
+            if not isinstance(value.get('value'),list):raise SourceUnavailable('invalid_source_response')
+            for row in value['value']:
+                if not isinstance(row,dict):raise SourceUnavailable('invalid_source_response')
+                if row.get('parentReference',{}).get('driveId')!=self.drive_id or not isinstance(row.get('file'),dict):continue
+                identity=row.get('id');identifier(identity)
+                if identity not in seen:seen.add(identity);result.append(identity)
+                if len(result)==limit:break
+            url=value.get('@odata.nextLink')
+        return tuple(result)
+
+    def metadata(self,identity,subject):
+        value=self._get('/drives/'+self.drive+'/items/'+identifier(identity)+'?'+urlencode({'$select':'id,name,eTag,file,parentReference,webUrl,deleted'}),subject)
+        if value.get('id')!=identity or value.get('deleted')or not isinstance(value.get('file'),dict)or value.get('parentReference',{}).get('driveId')!=self.drive_id or not isinstance(value.get('eTag'),str)or not value['eTag']:
+            raise SourceDenied('source_document_unavailable')
+        checked_url(value.get('webUrl',''),{self.host})
+        return value
+
+    def fetch(self,identity,subject,decode):
+        self.identify(subject);before=self.metadata(identity,subject)
+        self.access.require(subject)
+        reply=self.http.get(self.base+'/drives/'+self.drive+'/items/'+identifier(identity)+'/content',self.access.token,hosts={'graph.microsoft.com'},limit=10000000)
+        if reply.status==302:
+            # Download capability URL is short lived: never persist/log it and
+            # never forward the Graph bearer token to the storage endpoint.
+            location=reply.headers.get('Location')or reply.headers.get('location')
+            checked_url(location,{self.host})
+            reply=self.http.get(location,None,hosts={self.host},limit=10000000)
+        if reply.status!=200:raise SourceUnavailable('source_download_failed')
+        def current():
+            value=self.metadata(identity,subject)
+            if value['eTag']!=before['eTag']:raise SourceChanged('source_document_changed')
+            return value
+        source_decoder=getattr(decode,'from_source',None)
+        mime=before['file'].get('mimeType','application/octet-stream')
+        text=source_decoder(reply.body,mime,current)if callable(source_decoder)else decode(reply.body,mime)
+        if not isinstance(text,str)or not text.strip()or len(text)>200000:raise SourceUnavailable('source_document_unsupported')
+        after=current()
+        title=after.get('name')
+        if not isinstance(title,str)or not title or len(title)>1000:raise SourceUnavailable('invalid_source_response')
+        return SourceDocument(self.source,identity,after['eTag'],title,text,after['webUrl'])
+
+    def revalidate(self,document,subject):
+        if document.source!=self.source or self.metadata(document.id,subject)['eTag']!=document.version:raise SourceChanged('source_document_changed')
+
+
+class PageText(HTMLParser):
+    def __init__(self):super().__init__(convert_charrefs=True);self.parts=[];self.hidden=0
+    def handle_starttag(self,tag,attrs):
+        if tag in {'script','style'}:self.hidden+=1
+        elif not self.hidden and tag in {'p','br','div','li','h1','h2','h3','tr'}:self.parts.append('\n')
+    def handle_endtag(self,tag):
+        if tag in {'script','style'}and self.hidden:self.hidden-=1
+    def handle_data(self,data):
+        if not self.hidden:self.parts.append(data)
+
+
+class ConfluenceCloud:
+    def __init__(self,cloud_id,site_host,spaces,access,*,http=None):
+        if not isinstance(cloud_id,str)or not re.fullmatch(r'[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}',cloud_id):raise SourceUnavailable('invalid_confluence_cloud')
+        if not isinstance(site_host,str)or not re.fullmatch(r'[a-z0-9][a-z0-9-]*\.atlassian\.net',site_host):raise SourceUnavailable('invalid_confluence_host')
+        if not isinstance(spaces,dict)or not spaces or len(spaces)>100 or any(not isinstance(k,str)or not re.fullmatch(r'[A-Za-z0-9_~-]{1,128}',k)or not isinstance(v,str)or not re.fullmatch(r'[0-9]{1,30}',v)for k,v in spaces.items()):raise SourceUnavailable('invalid_confluence_spaces')
+        self.source='confluence:'+cloud_id;self.cloud_id=cloud_id;self.base='https://api.atlassian.com/ex/confluence/'+cloud_id;self.host=site_host;self.space_ids=set(spaces.values());self.space_keys=set(spaces);self.access=access;self.http=http or NativeHttp()
+
+    def _get(self,path,subject):
+        self.access.require(subject)
+        return decoded(self.http.get(self.base+path,self.access.token,hosts={'api.atlassian.com'}))
+
+    def identify(self,subject):
+        self.access.require(subject)
+        value=decoded(self.http.get('https://api.atlassian.com/me',self.access.token,hosts={'api.atlassian.com'}))
+        if value.get('account_id')!=self.access.source_subject or value.get('account_status')!='active':raise SourceDenied('source_identity_mismatch')
+        reply=self.http.get('https://api.atlassian.com/oauth/token/accessible-resources',self.access.token,hosts={'api.atlassian.com'})
+        try:resources=json.loads(reply.body)
+        except (ValueError,UnicodeError):raise SourceUnavailable('invalid_source_response')from None
+        if reply.status!=200 or not isinstance(resources,list):raise SourceUnavailable('invalid_source_response')
+        allowed=[r for r in resources if isinstance(r,dict)and r.get('id')==self.cloud_id and r.get('url')=='https://'+self.host]
+        if len(allowed)!=1 or not isinstance(allowed[0].get('scopes'),list)or 'read:page:confluence'not in allowed[0]['scopes']or not {'search:confluence','read:content-details:confluence'}.intersection(allowed[0]['scopes']):raise SourceDenied('source_site_unavailable')
+
+    def search(self,question,subject,*,limit=20):
+        if type(limit)is not int or not 1<=limit<=100:raise SourceUnavailable('invalid_search_limit')
+        self.identify(subject);term=query_text(question).replace('\\','\\\\').replace('"','\\"')
+        # IDs and query are data, never executable caller-supplied CQL.
+        cql='type=page AND space in ('+','.join('"'+key+'"'for key in sorted(self.space_keys))+') AND text ~ "'+term+'"'
+        route='/wiki/rest/api/search';url=self.base+route+'?'+urlencode({'cql':cql,'limit':min(limit,25)})
+        result=[];seen=set();pages=set()
+        while url and len(result)<limit:
+            checked_url(url,{'api.atlassian.com'})
+            if urlsplit(url).path!=urlsplit(self.base+route).path or url in pages or len(pages)>=20:raise SourceUnavailable('invalid_source_paging')
+            self.access.require(subject);pages.add(url)
+            value=decoded(self.http.get(url,self.access.token,hosts={'api.atlassian.com'}))
+            if not isinstance(value.get('results'),list):raise SourceUnavailable('invalid_source_response')
+            for row in value['results']:
+                content=row.get('content',{})if isinstance(row,dict)else{}
+                identity=content.get('id')
+                if content.get('type')!='page':continue
+                if not isinstance(identity,str)or not re.fullmatch(r'[0-9]{1,30}',identity):raise SourceUnavailable('invalid_source_response')
+                if identity not in seen:seen.add(identity);result.append(identity)
+                if len(result)==limit:break
+            next_url=value.get('_links',{}).get('next');url=None
+            if next_url:
+                if next_url.startswith('/rest/api/search?'):url=self.base+'/wiki'+next_url
+                elif next_url.startswith('/wiki/rest/api/search?'):url=self.base+next_url
+                else:url=next_url
+        return tuple(result)
+
+    def fetch(self,identity,subject,decode=None):
+        if not isinstance(identity,str)or not re.fullmatch(r'[0-9]{1,30}',identity):raise SourceUnavailable('invalid_source_identifier')
+        self.identify(subject)
+        value=self._get('/wiki/api/v2/pages/'+identity+'?body-format=storage',subject)
+        if value.get('id')!=identity or value.get('status')!='current'or value.get('spaceId')not in self.space_ids:raise SourceDenied('source_document_unavailable')
+        version=value.get('version',{}).get('number');title=value.get('title');html=value.get('body',{}).get('storage',{}).get('value')
+        if type(version)is not int or version<1 or not isinstance(title,str)or not title or len(title)>1000 or not isinstance(html,str)or len(html)>1000000:raise SourceUnavailable('invalid_source_response')
+        parser=PageText();parser.feed(html);text=''.join(parser.parts).strip()
+        if not text or len(text)>200000:raise SourceUnavailable('source_document_unsupported')
+        # Construct a fixed same-site citation, never an API-supplied redirect URL.
+        return SourceDocument(self.source,identity,str(version),title,text,'https://'+self.host+'/wiki/pages/viewpage.action?pageId='+identity)
+
+    def revalidate(self,document,subject):
+        if document.source!=self.source or self.fetch(document.id,subject).version!=document.version:raise SourceChanged('source_document_changed')

package/src/runtime/enterprise_web.py

@@ -0,0 +1,39 @@
+"""Owned static browser assets and public OIDC registration configuration."""
+import hashlib
+import json
+from pathlib import Path
+from urllib.parse import urlsplit
+from fastapi.responses import FileResponse
+from enterprise_identity import trusted_https
+
+
+def company_configuration(identity,config):
+    if not isinstance(config,dict)or set(config)!={'clientId','authorizationEndpoint','tokenEndpoint','scopes'}:raise ValueError('Supply only public company OIDC registration fields')
+    if not isinstance(config['clientId'],str)or not 1<=len(config['clientId'])<=200:raise ValueError('Use the owned public company client ID')
+    authorization=trusted_https(config['authorizationEndpoint']);token=trusted_https(config['tokenEndpoint'])
+    scopes=config['scopes']
+    if not isinstance(scopes,list)or not 3<=len(scopes)<=8 or any(not isinstance(scope,str)or not 1<=len(scope)<=300 or any(c.isspace()for c in scope)for scope in scopes)or len(set(scopes))!=len(scopes)or not {'openid','profile'}.issubset(scopes)or 'offline_access'in scopes or not any(scope==identity.scope or scope.endswith('/'+identity.scope)for scope in scopes):raise ValueError('Use OIDC and the owned delegated API scope without browser refresh credentials')
+    return {'issuer':identity.issuer,'clientId':config['clientId'],'authorizationEndpoint':authorization,'tokenEndpoint':token,'scopes':list(scopes)}
+
+
+def install_web(app,identity,connections,config,static_root=None):
+    company=company_configuration(identity,config)
+    token=company['tokenEndpoint']
+    root=Path(static_root)if static_root is not None else Path(__file__).parent
+    lock=json.loads((root/'enterprise-web-lock.json').read_text())
+    if hashlib.sha256((root/'enterprise-web-app.js').read_bytes()).hexdigest()!=lock['bundleSha256']:raise ValueError('Use the exact reviewed browser bundle')
+    # Native source constructors already validate these tenant citation hosts.
+    hosts=sorted({entry.driver.host for entry in connections.values()})
+    public={'company':company,'citationHosts':hosts,'authorizationOrigins':['https://login.microsoftonline.com','https://auth.atlassian.com']}
+    @app.get('/api/web-config')
+    def web_config():return public
+    @app.get('/')
+    @app.get('/company-callback')
+    def index():return FileResponse(root/'enterprise-web.html',media_type='text/html')
+    @app.get('/assets/workspace.js')
+    def javascript():return FileResponse(root/'enterprise-web-app.js',media_type='application/javascript')
+    @app.get('/assets/workspace.css')
+    def stylesheet():return FileResponse(root/'enterprise-web.css',media_type='text/css')
+    @app.get('/assets/notices.txt')
+    def notices():return FileResponse(root/'enterprise-web-notices.txt',media_type='text/plain')
+    return "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self' "+urlsplit(token).scheme+'://'+urlsplit(token).netloc+"; frame-ancestors 'none'; base-uri 'none'; form-action 'self'"