feat(quick-261009-dkv): Teilen mit Personen und Gruppen - Durchstich, Schnittstelle

- Freigaben-Schicht (nextcloud-shares.ts): eigener OCS-Aufruf, der Fehlertexte liest,
  Parser fuer Freigaben, Empfaenger und Freigaberegeln, Berechtigungsabbildung
- Dienst mit Vorpruefung aus den Faehigkeiten, Dublettenpruefung und Fehlermatrix
  (nie 401/403 nach aussen), Begrenzung auf 15 neue Freigaben in 10 Minuten
- Routen shares/policy, shares/by-path, sharees, POST/PUT/DELETE shares
- oc:share-types als shareTypes an jedem Eintrag
- Live-Test e2e-shares.sh (Abschnitt people)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-10-09 10:40:39 +02:00
parent 43a6a83347
commit 207d37b8d6
15 changed files with 2584 additions and 5 deletions
@@ -0,0 +1,519 @@
import { Readable } from 'node:stream';
import { describe, expect, it, vi } from 'vitest';
import { NextcloudCallGate } from './nextcloud-call-gate';
import { type NcSession } from './nextcloud-files.types';
import { NextcloudFilesSharesService } from './nextcloud-files-shares.service';
import type { NcTransportRequest, NextcloudTransport } from './nextcloud-http';
import { NextcloudLoginGuard } from './nextcloud-login-guard';
const SESSION: NcSession = {
baseUrl: 'https://cloud.example/nc',
ncUserId: 'anna',
authorization: 'Basic YW5uYTphcHAtcHctMTIz',
credentialKey: 'k1',
};
const OCS = 'https://cloud.example/nc/ocs/v2.php';
const SHARES = `${OCS}/apps/files_sharing/api/v1/shares`;
const BY_PATH = `${SHARES}?path=%2FProjekte&reshares=true`;
const CAPS_URL = `${OCS}/cloud/capabilities`;
const DAV = 'https://cloud.example/nc/remote.php/dav/files/anna';
const NS = 'xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns"';
function statXml(name: string, folder: boolean, letters: string): string {
return `<?xml version="1.0"?><d:multistatus ${NS}><d:response>
<d:href>/nc/remote.php/dav/files/anna/${name}</d:href><d:propstat><d:prop>
<d:resourcetype>${folder ? '<d:collection/>' : ''}</d:resourcetype>
<oc:fileid>7</oc:fileid><oc:permissions>${letters}</oc:permissions>
${folder ? '' : '<d:getcontentlength>5</d:getcontentlength><d:getcontenttype>text/plain</d:getcontenttype>'}
</d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat></d:response></d:multistatus>`;
}
const ocs = (data: unknown, status = 200, message = 'OK') =>
JSON.stringify({ ocs: { meta: { statuscode: status, message }, data } });
const CAPS = (over: Record<string, unknown> = {}) =>
ocs({
capabilities: {
password_policy: { minLength: 10 },
files_sharing: {
api_enabled: true,
group_sharing: true,
public: { enabled: true, upload: true },
sharee: { minSearchStringLength: 0 },
...over,
},
},
});
function shareJson(over: Record<string, unknown> = {}) {
return {
id: '17',
share_type: 0,
uid_owner: 'anna',
displayname_owner: 'Anna Müller',
permissions: 15,
can_edit: true,
can_delete: true,
stime: 1791532378,
path: '/Projekte',
item_type: 'folder',
item_permissions: 31,
mimetype: 'httpd/unix-directory',
file_target: '/Projekte',
share_with: 'ben',
share_with_displayname: 'Ben Beispiel',
...over,
};
}
type Reply = { status: number; text?: string; headers?: Record<string, string> };
function setup(replies: Reply[]) {
const calls: NcTransportRequest[] = [];
const queue = [...replies];
const transport: NextcloudTransport = async (req) => {
calls.push(req);
const reply = queue.shift();
if (!reply) throw new Error(`unerwarteter Aufruf ${req.method} ${req.url}`);
return {
statusCode: reply.status,
headers: reply.headers ?? {},
body: Readable.from(reply.text !== undefined ? [Buffer.from(reply.text)] : []),
};
};
const account = {
getSession: vi.fn(async (..._a: unknown[]) => SESSION),
markExpired: vi.fn(async (..._a: unknown[]) => {}),
};
const guard = new NextcloudLoginGuard();
const clock = { t: 1_000_000 };
guard.now = () => clock.t;
const service = new NextcloudFilesSharesService(
account as never,
new NextcloudCallGate(),
transport,
guard,
);
return { service, account, calls, queue, clock, guard };
}
const codeOf = (e: unknown) => (e as { response: { code: string } }).response.code;
const bodyOf = (e: unknown) => (e as { response: Record<string, unknown> }).response;
const statusOf = (e: unknown) => (e as { getStatus(): number }).getStatus();
async function failure(promise: Promise<unknown>): Promise<unknown> {
try {
await promise;
} catch (e) {
return e;
}
throw new Error('es wurde kein Fehler geworfen');
}
/** Antworten fuer ein erfolgreiches create(): stat, Faehigkeiten, Liste des Pfads, POST. */
function createReplies(
over: { stat?: Reply; caps?: Reply; list?: Reply; post?: Reply } = {},
): Reply[] {
return [
over.stat ?? { status: 207, text: statXml('Projekte', true, 'RGDNVCK') },
over.caps ?? { status: 200, text: CAPS() },
over.list ?? { status: 200, text: ocs([]) },
over.post ?? { status: 200, text: ocs(shareJson()) },
];
}
const INPUT = { path: '/Projekte', kind: 'user', shareWith: 'ben', access: 'edit' } as const;
describe('NextcloudFilesSharesService — create', () => {
it('sendet PROPFIND, Faehigkeiten, Liste des Pfads, POST in dieser Reihenfolge und liefert die Freigabe', async () => {
const { service, account, calls } = setup(createReplies());
const share = await service.create('t1', 'u1', INPUT);
expect(account.getSession).toHaveBeenCalledWith('t1', 'u1');
expect(calls.map((c) => `${c.method} ${c.url}`)).toEqual([
`PROPFIND ${DAV}/Projekte`,
`GET ${CAPS_URL}`,
`GET ${BY_PATH}`,
`POST ${SHARES}`,
]);
expect(calls[0].headers.depth).toBe('0');
expect(calls[3].headers['content-type']).toBe('application/json');
expect(calls[3].body).toBe(
'{"path":"/Projekte","shareType":0,"shareWith":"ben","permissions":15}',
);
expect(share).toMatchObject({ id: '17', kind: 'user', shareWith: 'ben', access: 'edit' });
});
it('Gruppe: shareType 1', async () => {
const { service, calls } = setup(
createReplies({
post: { status: 200, text: ocs(shareJson({ share_type: 1, share_with: 'team' })) },
}),
);
const share = await service.create('t1', 'u1', { ...INPUT, kind: 'group', shareWith: 'team' });
expect(calls[3].body).toBe(
'{"path":"/Projekte","shareType":1,"shareWith":"team","permissions":15}',
);
expect(share.kind).toBe('group');
});
it('Datei: Bearbeiten sendet 3, Ansehen sendet 1', async () => {
for (const [access, permissions] of [
['edit', 3],
['view', 1],
] as const) {
const { service, calls } = setup([
{ status: 207, text: statXml('Bericht.txt', false, 'RGDNVW') },
{ status: 200, text: CAPS() },
{ status: 200, text: ocs([]) },
{
status: 200,
text: ocs(shareJson({ path: '/Bericht.txt', item_type: 'file', permissions })),
},
]);
await service.create('t1', 'u1', { ...INPUT, path: '/Bericht.txt', access });
expect(calls[2].url).toBe(`${SHARES}?path=%2FBericht.txt&reshares=true`);
expect(calls[3].body).toBe(
`{"path":"/Bericht.txt","shareType":0,"shareWith":"ben","permissions":${permissions}}`,
);
}
});
it('Hochladen fuer eine Person, oder Bearbeiten bei Buchstaben RG: 400 shareAccessInvalid, kein POST', async () => {
const upload = setup(createReplies());
const e1 = await failure(upload.service.create('t1', 'u1', { ...INPUT, access: 'upload' }));
expect(codeOf(e1)).toBe('shareAccessInvalid');
expect(statusOf(e1)).toBe(400);
expect(upload.calls.some((c) => c.method === 'POST')).toBe(false);
const readonly = setup(
createReplies({ stat: { status: 207, text: statXml('Projekte', true, 'RG') } }),
);
const e2 = await failure(readonly.service.create('t1', 'u1', INPUT));
expect(codeOf(e2)).toBe('shareAccessInvalid');
expect(readonly.calls.some((c) => c.method === 'POST')).toBe(false);
});
it('der Empfaenger hat schon eine Freigabe: 409 shareAlreadyExists, kein POST', async () => {
const { service, calls } = setup(
createReplies({ list: { status: 200, text: ocs([shareJson()]) } }),
);
const e = await failure(service.create('t1', 'u1', INPUT));
expect(codeOf(e)).toBe('shareAlreadyExists');
expect(statusOf(e)).toBe(409);
expect(calls.some((c) => c.method === 'POST')).toBe(false);
});
it('gleiche Kennung als Gruppe zaehlt nicht als vorhandene Personenfreigabe', async () => {
const { service } = setup(
createReplies({
list: { status: 200, text: ocs([shareJson({ share_type: 1, share_with: 'ben' })]) },
}),
);
await expect(service.create('t1', 'u1', INPUT)).resolves.toMatchObject({ id: '17' });
});
it('Gruppen ausgeschaltet: 409 sharingDisabled mit der Gruppenmeldung, kein POST', async () => {
const { service, calls } = setup(
createReplies({ caps: { status: 200, text: CAPS({ group_sharing: false }) } }),
);
const e = await failure(
service.create('t1', 'u1', { ...INPUT, kind: 'group', shareWith: 'team' }),
);
expect(codeOf(e)).toBe('sharingDisabled');
expect(statusOf(e)).toBe(409);
expect(bodyOf(e).message).toBe('Teilen mit Gruppen ist in Ihrer Nextcloud ausgeschaltet.');
expect(calls.some((c) => c.method === 'POST')).toBe(false);
});
it('Freigabe-Schnittstelle aus: 409 sharingDisabled', async () => {
const { service, calls } = setup(
createReplies({ caps: { status: 200, text: CAPS({ api_enabled: false }) } }),
);
const e = await failure(service.create('t1', 'u1', INPUT));
expect(codeOf(e)).toBe('sharingDisabled');
expect(bodyOf(e).message).toBe('Teilen ist in Ihrer Nextcloud ausgeschaltet.');
expect(calls.some((c) => c.method === 'POST')).toBe(false);
});
it('leerer Pfad oder Wurzel: 400 invalidPath ohne jeden Aufruf', async () => {
for (const path of ['', '/']) {
const { service, account, calls } = setup([]);
const e = await failure(service.create('t1', 'u1', { ...INPUT, path }));
expect(codeOf(e)).toBe('invalidPath');
expect(calls).toHaveLength(0);
expect(account.getSession).not.toHaveBeenCalled();
}
});
it('Eintrag nicht vorhanden: 404 notFound, danach kein Freigabe-Aufruf', async () => {
const { service, calls } = setup([{ status: 404 }]);
const e = await failure(service.create('t1', 'u1', INPUT));
expect(codeOf(e)).toBe('notFound');
expect(calls).toHaveLength(1);
});
it.each([
[404, undefined, 422, 'shareRecipientInvalid'],
[403, 'You cannot share a folder that contains other shares', 422, 'shareRejected'],
[400, undefined, 422, 'shareRejected'],
[500, undefined, 502, 'nextcloudError'],
[503, undefined, 503, 'nextcloudMaintenance'],
])('POST antwortet %i -> %i %s', async (nc, message, http, code) => {
const { service } = setup(
createReplies({
post: {
status: nc,
text: JSON.stringify({
ocs: { meta: { statuscode: nc, message: message ?? 'x' }, data: [] },
}),
},
}),
);
const e = await failure(service.create('t1', 'u1', INPUT));
expect(codeOf(e)).toBe(code);
expect(statusOf(e)).toBe(http);
expect([401, 403]).not.toContain(statusOf(e));
if (code === 'shareRejected' && message) expect(bodyOf(e).ncMessage).toBe(message);
});
it('POST antwortet 401: 409 connectionExpired und die Verbindung ist als abgelaufen markiert', async () => {
const { service, account } = setup(createReplies({ post: { status: 401 } }));
const e = await failure(service.create('t1', 'u1', INPUT));
expect(codeOf(e)).toBe('connectionExpired');
expect(statusOf(e)).toBe(409);
expect(account.markExpired).toHaveBeenCalledTimes(1);
expect(account.markExpired).toHaveBeenCalledWith('t1', 'u1');
});
it('POST antwortet 429: 503 nextcloudLocked', async () => {
const { service } = setup(
createReplies({ post: { status: 429, headers: { 'retry-after': '60' } } }),
);
const e = await failure(service.create('t1', 'u1', INPUT));
expect(codeOf(e)).toBe('nextcloudLocked');
expect(statusOf(e)).toBe(503);
});
});
describe('NextcloudFilesSharesService — Begrenzung neuer Freigaben', () => {
it('15 in 10 Minuten gehen durch, die 16. ist 429 tooManyShares ohne Aufruf, nach 10 Minuten geht es wieder', async () => {
const replies: Reply[] = [];
for (let i = 0; i < 15; i++) replies.push(...createReplies());
// der abgewiesene 16. Versuch verbraucht nur die Vorpruefungen, nie den POST
replies.push(...createReplies().slice(0, 3));
replies.push(...createReplies());
const { service, calls, clock } = setup(replies);
for (let i = 0; i < 15; i++) {
await service.create('t1', 'u1', { ...INPUT, shareWith: `ben${i}` });
}
const before = calls.length;
const e = await failure(service.create('t1', 'u1', { ...INPUT, shareWith: 'ben15' }));
expect(codeOf(e)).toBe('tooManyShares');
expect(statusOf(e)).toBe(429);
expect(bodyOf(e).retryAfterSeconds).toBe(600);
// Vorpruefungen laufen, aber der POST wird nicht gesendet.
expect(calls.slice(before).some((c) => c.method === 'POST')).toBe(false);
clock.t += 10 * 60 * 1000;
await expect(
service.create('t1', 'u1', { ...INPUT, shareWith: 'ben15' }),
).resolves.toBeTruthy();
});
it('eine durch Vorpruefung abgelehnte Eingabe zaehlt nicht mit', async () => {
const replies: Reply[] = [];
for (let i = 0; i < 3; i++) {
replies.push(
...createReplies({
list: { status: 200, text: ocs([shareJson({ share_with: 'x' })]) },
}).slice(0, 3),
);
}
for (let i = 0; i < 15; i++) replies.push(...createReplies());
const { service } = setup(replies);
for (let i = 0; i < 3; i++) {
const e = await failure(service.create('t1', 'u1', { ...INPUT, shareWith: 'x' }));
expect(codeOf(e)).toBe('shareAlreadyExists');
}
for (let i = 0; i < 15; i++) await service.create('t1', 'u1', { ...INPUT, shareWith: `b${i}` });
});
});
describe('NextcloudFilesSharesService — update', () => {
const GET17 = `GET ${SHARES}/17`;
it('Ansehen: GET der Freigabe, dann PUT nur mit der neuen Berechtigung', async () => {
const { service, calls } = setup([
{ status: 200, text: ocs([shareJson()]) },
{ status: 200, text: ocs(shareJson({ permissions: 1 })) },
]);
const share = await service.update('t1', 'u1', '17', { access: 'view' });
expect(calls.map((c) => `${c.method} ${c.url}`)).toEqual([GET17, `PUT ${SHARES}/17`]);
expect(calls[1].body).toBe('{"permissions":1}');
expect(share.access).toBe('view');
});
it('Freigabe nicht aenderbar (can_edit false): 422 shareRejected ohne PUT', async () => {
const { service, calls } = setup([
{ status: 200, text: ocs([shareJson({ can_edit: false })]) },
]);
const e = await failure(service.update('t1', 'u1', '17', { access: 'view' }));
expect(codeOf(e)).toBe('shareRejected');
expect(statusOf(e)).toBe(422);
expect(calls).toHaveLength(1);
});
it('PUT 404 -> 404 shareNotFound', async () => {
const { service } = setup([
{ status: 200, text: ocs([shareJson()]) },
{ status: 404, text: ocs([], 404, 'Wrong share ID, share does not exist') },
]);
const e = await failure(service.update('t1', 'u1', '17', { access: 'view' }));
expect(codeOf(e)).toBe('shareNotFound');
expect(statusOf(e)).toBe(404);
});
it('PUT 400 und 403 -> 422 shareRejected mit Meldung der Nextcloud', async () => {
for (const nc of [400, 403]) {
const { service } = setup([
{ status: 200, text: ocs([shareJson()]) },
{ status: nc, text: ocs([], nc, 'Failed to update share.') },
]);
const e = await failure(service.update('t1', 'u1', '17', { access: 'view' }));
expect(codeOf(e)).toBe('shareRejected');
expect(statusOf(e)).toBe(422);
expect(bodyOf(e).ncMessage).toBe('Failed to update share.');
}
});
it("Kennung 'abc' und eine 21-stellige Kennung: 404 shareNotFound ohne Aufruf", async () => {
for (const id of ['abc', '1'.repeat(21), '../x', '']) {
const { service, calls } = setup([]);
const e = await failure(service.update('t1', 'u1', id, { access: 'view' }));
expect(codeOf(e)).toBe('shareNotFound');
expect(calls).toHaveLength(0);
}
});
it('ohne Aenderung kommt die aktuelle Freigabe zurueck, es gibt kein PUT', async () => {
const { service, calls } = setup([{ status: 200, text: ocs([shareJson()]) }]);
const share = await service.update('t1', 'u1', '17', {});
expect(share.id).toBe('17');
expect(calls).toHaveLength(1);
});
it('gleiche Berechtigung wie bisher: kein PUT', async () => {
const { service, calls } = setup([{ status: 200, text: ocs([shareJson()]) }]);
await service.update('t1', 'u1', '17', { access: 'edit' });
expect(calls).toHaveLength(1);
});
it('Bearbeiten bei einem Eintrag ohne Schreibrecht und Hochladen sind shareAccessInvalid', async () => {
const ro = setup([
{ status: 200, text: ocs([shareJson({ permissions: 1, item_permissions: 17 })]) },
]);
expect(codeOf(await failure(ro.service.update('t1', 'u1', '17', { access: 'edit' })))).toBe(
'shareAccessInvalid',
);
const up = setup([{ status: 200, text: ocs([shareJson()]) }]);
expect(codeOf(await failure(up.service.update('t1', 'u1', '17', { access: 'upload' })))).toBe(
'shareAccessInvalid',
);
});
it('GET der Freigabe 404 -> shareNotFound; 401 markiert die Verbindung', async () => {
const gone = setup([{ status: 404, text: ocs([], 404, 'Wrong share ID') }]);
expect(codeOf(await failure(gone.service.update('t1', 'u1', '17', { access: 'view' })))).toBe(
'shareNotFound',
);
const dead = setup([{ status: 401 }]);
const e = await failure(dead.service.update('t1', 'u1', '17', { access: 'view' }));
expect(codeOf(e)).toBe('connectionExpired');
expect(dead.account.markExpired).toHaveBeenCalledTimes(1);
});
});
describe('NextcloudFilesSharesService — remove, lesen, Richtlinie', () => {
it('remove: DELETE auf die Kennung', async () => {
const { service, calls } = setup([{ status: 200, text: ocs([]) }]);
await expect(service.remove('t1', 'u1', '17')).resolves.toEqual({ deleted: true });
expect(calls[0].method).toBe('DELETE');
expect(calls[0].url).toBe(`${SHARES}/17`);
expect(calls[0].body).toBeNull();
});
it('remove: 404 -> shareNotFound, 403 -> 422 shareRejected, falsche Kennung ohne Aufruf', async () => {
const nf = setup([{ status: 404, text: ocs([], 404, 'Wrong share ID') }]);
expect(codeOf(await failure(nf.service.remove('t1', 'u1', '17')))).toBe('shareNotFound');
const forbidden = setup([{ status: 403, text: ocs([], 403, 'Could not delete share') }]);
const e = await failure(forbidden.service.remove('t1', 'u1', '17'));
expect(codeOf(e)).toBe('shareRejected');
expect(statusOf(e)).toBe(422);
expect(bodyOf(e).ncMessage).toBe('Could not delete share');
const bad = setup([]);
expect(codeOf(await failure(bad.service.remove('t1', 'u1', 'abc')))).toBe('shareNotFound');
expect(bad.calls).toHaveLength(0);
});
it('Freigaben eines Pfads: Pfad normalisiert, Wurzel ist invalidPath', async () => {
const { service, calls } = setup([
{ status: 200, text: ocs([shareJson(), { share_type: 4, id: '9' }]) },
]);
const out = await service.sharesForPath('t1', 'u1', '/Projekte/');
expect(calls[0].url).toBe(BY_PATH);
expect(out.path).toBe('/Projekte');
expect(out.shares.map((s) => s.id)).toEqual(['17']);
expect(out.hidden).toBe(1);
const root = setup([]);
expect(codeOf(await failure(root.service.sharesForPath('t1', 'u1', '/')))).toBe('invalidPath');
const nf = setup([{ status: 404, text: ocs([], 404, 'Wrong path') }]);
expect(codeOf(await failure(nf.service.sharesForPath('t1', 'u1', '/x')))).toBe('notFound');
});
it('Empfaengersuche: genau die erwartete Adresse; leerer Suchbegriff ruft nichts auf', async () => {
const { service, calls } = setup([
{
status: 200,
text: ocs({
users: [
{
label: 'Ben Beispiel',
value: { shareType: 0, shareWith: 'ben' },
shareWithDisplayNameUnique: 'ben',
},
],
groups: [],
}),
},
]);
const out = await service.sharees('t1', 'u1', ' ben ', 'folder');
expect(calls[0].url).toBe(
`${OCS}/apps/files_sharing/api/v1/sharees?search=ben&itemType=folder&perPage=20&shareType%5B0%5D=0&shareType%5B1%5D=1`,
);
expect(out.sharees).toEqual([
{ kind: 'user', id: 'ben', label: 'Ben Beispiel', detail: 'ben' },
]);
const empty = setup([]);
await expect(empty.service.sharees('t1', 'u1', ' ', 'file')).resolves.toEqual({ sharees: [] });
expect(empty.calls).toHaveLength(0);
});
it('Richtlinie: zwei Aufrufe -> zwei Anfragen an die Faehigkeiten (kein Zwischenspeicher)', async () => {
const { service, calls } = setup([
{ status: 200, text: CAPS() },
{ status: 200, text: CAPS({ group_sharing: false }) },
]);
const first = await service.policy('t1', 'u1');
const second = await service.policy('t1', 'u1');
expect(calls.map((c) => c.url)).toEqual([CAPS_URL, CAPS_URL]);
expect(first.groupsEnabled).toBe(true);
expect(second.groupsEnabled).toBe(false);
});
it('nie 401 oder 403 nach aussen, auch nicht bei 403 aus der Suche', async () => {
const { service } = setup([{ status: 403, text: ocs([], 403, 'nope') }]);
const e = await failure(service.sharees('t1', 'u1', 'be', 'file'));
expect([401, 403]).not.toContain(statusOf(e));
});
});